robot_lab-a2a 0.1.0

data/examples/run

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run a demo end-to-end: starts the server, waits until it accepts
+# connections, runs the client, then shuts the server down.
+#
+# Usage (from the project root):
+#   bundle exec ruby examples/run 01_sync_robot
+#
+# Usage (from inside examples/):
+#   ./run 01_sync_robot
+
+require 'rubygems'
+require 'socket'
+
+EXAMPLES_DIR    = File.expand_path(__dir__)
+RUBY            = RbConfig.ruby
+BUNDLE          = Gem.bin_path('bundler', 'bundle')
+SERVER_PORT     = 9292
+STARTUP_TIMEOUT = 15 # seconds
+
+# ---------------------------------------------------------------------------
+# Argument handling
+# ---------------------------------------------------------------------------
+name = ARGV.first&.chomp('/')
+
+unless name
+  puts 'Usage: run <demo-name>'
+  puts
+  puts 'Available demos:'
+  Dir["#{EXAMPLES_DIR}/*/server.rb"].each do |f|
+    puts "  #{File.basename(File.dirname(f))}"
+  end
+  exit 1
+end
+
+demo_dir = File.join(EXAMPLES_DIR, name)
+
+abort "Demo not found: #{demo_dir}" unless File.directory?(demo_dir)
+
+# If the demo has its own run script, delegate to it.
+custom_runner = File.join(demo_dir, 'run')
+exec(RUBY, custom_runner, *ARGV.drop(1)) if File.exist?(custom_runner)
+
+server_rb = File.join(demo_dir, 'server.rb')
+client_rb = File.join(demo_dir, 'client.rb')
+
+abort "Missing server.rb in #{demo_dir}" unless File.exist?(server_rb)
+abort "Missing client.rb in #{demo_dir}" unless File.exist?(client_rb)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def banner(text)
+  bar = '─' * (text.length + 4)
+  puts "┌#{bar}┐"
+  puts "│  #{text}  │"
+  puts "└#{bar}┘"
+end
+
+def server_ready?(port)
+  TCPSocket.new('localhost', port).close
+  true
+rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, Errno::ETIMEDOUT
+  false
+end
+
+def wait_for_server(port, timeout)
+  deadline = Time.now + timeout
+  sleep 0.05 until server_ready?(port) || Time.now > deadline
+  server_ready?(port)
+end
+
+# ---------------------------------------------------------------------------
+# Start server
+# ---------------------------------------------------------------------------
+banner "Starting #{name} — server"
+server_pid = spawn(BUNDLE, 'exec', RUBY, server_rb, out: $stdout, err: $stderr)
+
+unless wait_for_server(SERVER_PORT, STARTUP_TIMEOUT)
+  begin
+    Process.kill('TERM', server_pid)
+  rescue StandardError
+    nil
+  end
+  abort "\nServer did not become ready within #{STARTUP_TIMEOUT}s — aborting."
+end
+
+puts "\n(server ready on port #{SERVER_PORT})\n\n"
+
+# ---------------------------------------------------------------------------
+# Run client
+# ---------------------------------------------------------------------------
+banner "Running #{name} — client"
+begin
+  client_ok = system(BUNDLE, 'exec', RUBY, client_rb)
+rescue Interrupt
+  client_ok = false
+end
+
+# ---------------------------------------------------------------------------
+# Shut down server
+# ---------------------------------------------------------------------------
+puts "\n(stopping server…)"
+begin
+  Process.kill('TERM', server_pid)
+  Process.wait(server_pid)
+rescue Errno::ESRCH, Errno::ECHILD
+  # already gone
+end
+
+exit(client_ok ? 0 : 1)

data/lib/robot_lab/a2a/ask_user_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    # Drop-in replacement for RobotLab::AskUser when a robot runs under A2A.
+    #
+    # Instead of blocking a terminal, it pushes an input_required event through
+    # the event_queue so the RobotAdapter can call task.require_input! and
+    # emit_status(final: true), then blocks on answer_queue until the A2A client
+    # resumes the task with another message.
+    #
+    # Inject before robot.run() via RobotAdapter — do not use directly.
+    class AskUserTool < RobotLab::Tool
+      description 'Ask the user a clarifying question and wait for their response'
+      param :question, type: 'string', desc: 'The question to present to the user'
+      param :choices,  type: 'array',  desc: 'Optional list of choices to present', required: false
+      param :default,  type: 'string', desc: 'Default value if user presses Enter', required: false
+
+      attr_writer :event_queue, :answer_queue
+
+      def execute(question:, choices: nil, default: nil)
+        raise 'A2A queues not injected — use RobotLab::A2A::RobotAdapter' unless @event_queue
+
+        prompt_text = format_prompt(question, choices, default)
+        prompt      = ::A2A::Models::Message.agent(prompt_text)
+        @event_queue.push({ type: :ask, prompt: prompt })
+
+        answer = @answer_queue.pop
+        answer = default if (answer.nil? || answer.strip.empty?) && default
+        answer.to_s
+      end
+
+      private
+
+      def format_prompt(question, choices, default)
+        lines = [question]
+        choices.each_with_index { |c, i| lines << "  #{i + 1}. #{c}" } if choices.is_a?(Array) && choices.any?
+        lines << "(Default: #{default})" if default
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/robot_lab/a2a/io_bridge.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    # IO-compatible wrapper for :io_bridge interactive mode.
+    #
+    # Inject as both robot.input and robot.output before robot.run().
+    # Output written by AskUser (the prompt text) is buffered; when AskUser
+    # calls gets(), the buffer becomes the input_required message and the call
+    # blocks until the A2A client resumes the task with an answer.
+    #
+    # This lets existing robots that use RobotLab::AskUser work under A2A
+    # without any modification — the terminal is replaced by the HTTP protocol.
+    #
+    # Only works with in-process storage: the robot thread must stay alive
+    # between INPUT_REQUIRED and resume.
+    class IoBridge
+      def initialize(event_queue:, answer_queue:)
+        @event_queue   = event_queue
+        @answer_queue  = answer_queue
+        @output_buffer = +''
+        @buffer_mutex  = Mutex.new
+      end
+
+      # --- output side (robot.output) ---
+
+      def print(*args)
+        @buffer_mutex.synchronize { @output_buffer << args.join }
+        nil
+      end
+
+      def puts(*args)
+        @buffer_mutex.synchronize do
+          if args.empty?
+            @output_buffer << "\n"
+          else
+            args.each { |a| @output_buffer << a.to_s << "\n" }
+          end
+        end
+        nil
+      end
+
+      def write(str)
+        @buffer_mutex.synchronize { @output_buffer << str.to_s }
+        str.to_s.length
+      end
+
+      def flush
+        self
+      end
+
+      def sync=(*)
+        # no-op — satisfy IO compatibility
+      end
+
+      # --- input side (robot.input) ---
+
+      def gets
+        prompt_text = @buffer_mutex.synchronize do
+          text = @output_buffer.dup.strip
+          @output_buffer.clear
+          text
+        end
+
+        prompt = ::A2A::Models::Message.agent(
+          prompt_text.empty? ? 'Input required:' : prompt_text
+        )
+        @event_queue.push({ type: :ask, prompt: prompt })
+
+        answer = @answer_queue.pop
+        "#{answer}\n"
+      end
+    end
+  end
+end

data/lib/robot_lab/a2a/network_adapter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    # Wraps a RobotLab::Network as an A2A AgentExecutor.
+    #
+    # Only :none interactive mode is supported — interactive flows require
+    # per-robot queue injection across all network robots, planned for a future
+    # release. Wrap individual robots with RobotAdapter for interactive flows.
+    class NetworkAdapter < ::A2A::Server::AgentExecutor
+      def initialize(network, interactive: :none)
+        super()
+        if interactive != :none
+          raise ArgumentError,
+                'NetworkAdapter only supports interactive: :none. ' \
+                'For interactive network flows, wrap individual robots with RobotAdapter.'
+        end
+
+        @network = network
+      end
+
+      def call(context)
+        context.task.start!
+        context.emit_status
+
+        input_text = context.message.text_content
+        reply      = @network.run(message: input_text).last_text_content
+
+        artifact = ::A2A::Models::Artifact.new(
+          parts: [::A2A::Models::Part.text(reply.to_s)],
+          name: 'reply'
+        )
+        context.task.complete!(artifacts: [artifact])
+        context.emit_status(final: true)
+      end
+    end
+  end
+end

data/lib/robot_lab/a2a/registry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    # Tracks live robot threads for in-progress interactive runs.
+    # Keyed by A2A task_id. Entries are removed when the robot thread finishes.
+    class Registry
+      Entry = Data.define(:thread, :event_queue, :answer_queue)
+
+      @mutex   = Mutex.new
+      @entries = {}
+
+      class << self
+        def register(task_id, entry)
+          @mutex.synchronize { @entries[task_id] = entry }
+        end
+
+        def fetch(task_id)
+          @mutex.synchronize { @entries[task_id] }
+        end
+
+        def delete(task_id)
+          @mutex.synchronize { @entries.delete(task_id) }
+        end
+
+        def size
+          @mutex.synchronize { @entries.size }
+        end
+
+        def clear
+          @mutex.synchronize { @entries.clear }
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/a2a/robot_adapter.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    # Wraps a RobotLab::Robot as an A2A AgentExecutor.
+    #
+    # Pass an instance as the executor: when building an A2A server:
+    #
+    #   adapter = RobotAdapter.new(robot, interactive: :none)
+    #   A2A.server(agent_card: card, executor: adapter).run
+    #
+    # interactive modes:
+    #   :none      — robot runs sync; AskUser would block stdin (not recommended)
+    #   :a2a_tool  — A2A::AskUserTool replaces AskUser; Thread+Queue bridge
+    #   :io_bridge — IoBridge replaces robot.input/output; Thread+Queue bridge
+    #
+    # Interactive modes keep the robot thread alive between A2A INPUT_REQUIRED
+    # and resume. Only works with in-process (Memory) storage.
+    class RobotAdapter < ::A2A::Server::AgentExecutor
+      VALID_MODES = %i[none a2a_tool io_bridge].freeze
+
+      def initialize(robot, interactive: :none)
+        super()
+        unless VALID_MODES.include?(interactive)
+          raise ArgumentError, "interactive must be one of #{VALID_MODES.inspect}"
+        end
+
+        @robot       = robot
+        @interactive = interactive
+      end
+
+      def call(context)
+        input_text = context.message.text_content
+        task_id    = context.task.id
+
+        case @interactive
+        when :none
+          run_simple(context, input_text)
+        when :a2a_tool, :io_bridge
+          run_interactive(context, input_text, task_id)
+        end
+      end
+
+      def cancel(context)
+        task_id = context.task.id
+        entry   = Registry.fetch(task_id)
+        if entry
+          entry.thread.kill
+          Registry.delete(task_id)
+        end
+        super
+      end
+
+      private
+
+      # ── :none mode ────────────────────────────────────────────
+
+      def run_simple(context, input_text)
+        context.task.start!
+        context.emit_status
+
+        reply    = @robot.run(input_text).reply
+        artifact = ::A2A::Models::Artifact.new(
+          parts: [::A2A::Models::Part.text(reply.to_s)],
+          name: 'reply'
+        )
+        context.task.complete!(artifacts: [artifact])
+        context.emit_status(final: true)
+      end
+
+      # ── interactive modes ─────────────────────────────────────
+
+      def run_interactive(context, input_text, task_id)
+        if context.is_a?(::A2A::Server::ResumeContext)
+          entry = Registry.fetch(task_id)
+          if entry
+            entry.answer_queue.push(context.resume_message.text_content)
+            monitor_task(context, entry, task_id)
+          else
+            context.task.fail!(message: 'No active session found for resumed task')
+            context.emit_status(final: true)
+          end
+        else
+          start_interactive_run(context, input_text, task_id)
+        end
+      end
+
+      def start_interactive_run(context, input_text, task_id)
+        event_queue  = Queue.new
+        answer_queue = Queue.new
+        robot        = @robot
+
+        context.task.start!
+        context.emit_status
+
+        thread = Thread.new do
+          setup_interactive_mode(robot, event_queue, answer_queue)
+          reply = robot.run(input_text).reply
+          event_queue.push({ type: :done, reply: reply })
+        rescue StandardError => e
+          event_queue.push({ type: :error, error: e })
+        ensure
+          teardown_interactive_mode(robot)
+          Registry.delete(task_id)
+        end
+
+        entry = Registry::Entry.new(
+          thread: thread,
+          event_queue: event_queue,
+          answer_queue: answer_queue
+        )
+        Registry.register(task_id, entry)
+
+        monitor_task(context, entry, task_id)
+      end
+
+      def monitor_task(context, entry, _task_id)
+        event = entry.event_queue.pop
+        case event[:type]
+        when :ask
+          context.task.require_input!(message: event[:prompt])
+          context.emit_status(final: true)
+        when :done
+          artifact = ::A2A::Models::Artifact.new(
+            parts: [::A2A::Models::Part.text(event[:reply].to_s)],
+            name: 'reply'
+          )
+          context.task.complete!(artifacts: [artifact])
+          context.emit_status(final: true)
+        when :error
+          context.task.fail!(message: event[:error].message)
+          context.emit_status(final: true)
+        end
+      end
+
+      # ── interactive setup / teardown ──────────────────────────
+
+      def setup_interactive_mode(robot, event_queue, answer_queue)
+        case @interactive
+        when :a2a_tool  then inject_ask_user_tool(robot, event_queue, answer_queue)
+        when :io_bridge then inject_io_bridge(robot, event_queue, answer_queue)
+        end
+      end
+
+      def teardown_interactive_mode(robot)
+        case @interactive
+        when :a2a_tool
+          restore_tools(robot)
+        when :io_bridge
+          robot.input  = nil
+          robot.output = nil
+        end
+      end
+
+      def inject_ask_user_tool(robot, event_queue, answer_queue)
+        tool = AskUserTool.new(robot: robot)
+        tool.event_queue  = event_queue
+        tool.answer_queue = answer_queue
+
+        without_ask_user = robot.local_tools.reject do |t|
+          t.is_a?(RobotLab::AskUser) || t.is_a?(AskUserTool)
+        end
+        robot.instance_variable_set(:@local_tools, without_ask_user + [tool])
+        robot.instance_variable_set(:@_a2a_injected_tool, tool)
+      end
+
+      def restore_tools(robot)
+        injected = robot.instance_variable_get(:@_a2a_injected_tool)
+        return unless injected
+
+        cleaned = robot.local_tools.reject { |t| t.equal?(injected) }
+        robot.instance_variable_set(:@local_tools, cleaned)
+        robot.remove_instance_variable(:@_a2a_injected_tool)
+      end
+
+      def inject_io_bridge(robot, event_queue, answer_queue)
+        bridge = IoBridge.new(event_queue: event_queue, answer_queue: answer_queue)
+        robot.input  = bridge
+        robot.output = bridge
+      end
+    end
+  end
+end

data/lib/robot_lab/a2a/server.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    # Thin builder that registers RobotLab robots and networks as A2A agents
+    # and delegates to simple_a2a for HTTP serving.
+    #
+    # Each robot or network is mounted at its own URL path. The path defaults
+    # to "/dns-label-of-name" and can be overridden with the path: keyword.
+    #
+    # @example Basic usage
+    #   server = RobotLab::A2A::Server.new
+    #   server.add_robot(my_robot)
+    #   server.run(port: 9292)
+    #
+    # @example Interactive robot (AskUser bridged to A2A input_required)
+    #   server = RobotLab::A2A::Server.new(interactive: :a2a_tool)
+    #   server.add_robot(my_robot)
+    #   server.run(port: 9292)
+    #
+    # @example Multiple agents
+    #   server = RobotLab::A2A::Server.new
+    #   server.add_robot(analyst, path: "/analyst")
+    #   server.add_robot(writer,  path: "/writer")
+    #   server.add_network(pipeline, name: "pipeline", path: "/pipeline")
+    #   server.run(port: 9292)
+    #
+    # @example Rack/Rails mount
+    #   map "/agents" do
+    #     run RobotLab::A2A::Server.new.add_robot(my_robot).to_app
+    #   end
+    class Server
+      DEFAULT_VERSION = '1.0'
+
+      def initialize(host: 'localhost', port: 9292, storage: nil, interactive: :none)
+        @host        = host
+        @port        = port
+        @storage     = storage || ::A2A::Storage::Memory.new
+        @interactive = interactive
+        @agents      = {}
+      end
+
+      # Register a robot as an A2A agent.
+      #
+      # @param robot [RobotLab::Robot]
+      # @param name [String, nil] overrides robot.name
+      # @param description [String, nil] overrides robot.description
+      # @param path [String, nil] URL path prefix (defaults to "/dns-label")
+      # @return [self] for chaining
+      def add_robot(robot, name: nil, description: nil, path: nil)
+        agent_name = (name || robot.name).to_s
+        agent_desc = description || robot.description || agent_name
+        agent_path = path || "/#{dns_label(agent_name)}"
+        adapter    = RobotAdapter.new(robot, interactive: @interactive)
+        card       = build_agent_card(agent_name, agent_desc, path: agent_path)
+
+        @agents[agent_path] = { agent_card: card, executor: adapter, storage: @storage }
+        self
+      end
+
+      # Register a network as a single A2A agent (non-interactive).
+      #
+      # @param network [RobotLab::Network]
+      # @param name [String] required — used for agent card and default path
+      # @param description [String, nil]
+      # @param path [String, nil] URL path prefix (defaults to "/dns-label")
+      # @return [self] for chaining
+      def add_network(network, name:, description: nil, path: nil)
+        if @interactive != :none
+          raise ArgumentError,
+                'NetworkAdapter only supports interactive: :none. ' \
+                'Wrap individual robots with RobotAdapter for interactive flows.'
+        end
+
+        agent_name = name.to_s
+        agent_desc = description || agent_name
+        agent_path = path || "/#{dns_label(agent_name)}"
+        adapter    = NetworkAdapter.new(network, interactive: :none)
+        card       = build_agent_card(agent_name, agent_desc, path: agent_path)
+
+        @agents[agent_path] = { agent_card: card, executor: adapter, storage: @storage }
+        self
+      end
+
+      # Start the Falcon HTTP server.
+      def run
+        ::A2A.multi_server(agents: @agents, host: @host, port: @port).run
+      end
+
+      # Return a Rack app for embedding in other servers (e.g. Rails, Puma).
+      def to_app
+        url_map = @agents.transform_values do |cfg|
+          ::A2A.server(
+            agent_card: cfg[:agent_card],
+            executor: cfg[:executor],
+            storage: cfg[:storage]
+          ).rack_app
+        end
+        Rack::URLMap.new(url_map)
+      end
+
+      private
+
+      def build_agent_card(name, description, path:)
+        ::A2A::Models::AgentCard.new(
+          name: name,
+          description: description,
+          version: DEFAULT_VERSION,
+          capabilities: ::A2A::Models::AgentCapabilities.new,
+          skills: [::A2A::Models::AgentSkill.new(name: 'chat', description: 'General conversation')],
+          interfaces: [
+            ::A2A::Models::AgentInterface.new(
+              type: 'A2A',
+              url: "http://#{@host}:#{@port}#{path}",
+              version: DEFAULT_VERSION
+            )
+          ]
+        )
+      end
+
+      # Convert a Ruby-style name to RFC 1123 DNS label format.
+      # Underscores become hyphens; characters outside [a-z0-9-] are dropped.
+      def dns_label(name)
+        name.to_s.downcase.gsub('_', '-').gsub(/[^a-z0-9-]/, '').gsub(/\A-+|-+\z/, '')
+      end
+    end
+  end
+end

data/lib/robot_lab/a2a/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module A2A
+    VERSION = '0.1.0'
+  end
+end

data/lib/robot_lab/a2a.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'robot_lab'
+require 'simple_a2a'
+require 'rack'
+
+require_relative 'a2a/version'
+require_relative 'a2a/registry'
+require_relative 'a2a/ask_user_tool'
+require_relative 'a2a/io_bridge'
+require_relative 'a2a/robot_adapter'
+require_relative 'a2a/network_adapter'
+require_relative 'a2a/server'
+
+module RobotLab
+  @_extensions = {} unless instance_variable_defined?(:@_extensions)
+
+  class << self
+    unless method_defined?(:register_extension) || respond_to?(:register_extension)
+      def register_extension(name, mod)
+        @_extensions[name.to_sym] = mod
+      end
+    end
+
+    unless method_defined?(:extension_loaded?) || respond_to?(:extension_loaded?)
+      def extension_loaded?(name)
+        @_extensions.key?(name.to_sym)
+      end
+    end
+
+    unless method_defined?(:extension) || respond_to?(:extension)
+      def extension(name)
+        @_extensions[name.to_sym]
+      end
+    end
+  end
+end
+
+RobotLab.register_extension(:a2a, RobotLab::A2A)