simple_a2a 0.1.0

data/examples/run

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run a demo app end-to-end: starts the server, waits until it accepts
+# connections, runs the client, then shuts the server down.
+#
+# Usage (from the project root):
+#   ruby examples/run 01_basic_usage
+#
+# Usage (from inside examples/):
+#   ./run 01_basic_usage
+
+require "socket"
+
+EXAMPLES_DIR = File.expand_path("..", __FILE__)
+RUBY         = RbConfig.ruby
+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"].sort.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")
+if File.exist?(custom_runner)
+  exec(RUBY, custom_runner, *ARGV.drop(1))
+end
+
+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(RUBY, server_rb, out: $stdout, err: $stderr)
+
+unless wait_for_server(SERVER_PORT, STARTUP_TIMEOUT)
+  Process.kill("TERM", server_pid) rescue nil
+  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(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/simple_a2a/client/base.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/http/internet"
+
+module A2A
+  module Client
+    class Base
+      def initialize(url:, headers: {})
+        @url     = url
+        @headers = headers
+      end
+
+      def agent_card
+        body = http_get("agentCard")
+        Models::AgentCard.from_hash(JSON.parse(body))
+      end
+
+      def send_task(message:, **opts)
+        result = rpc_call("tasks/send", build_send_params(message, opts))
+        Models::Task.from_hash(result)
+      end
+
+      def get_task(task_id)
+        result = rpc_call("tasks/get", { "id" => task_id })
+        Models::Task.from_hash(result)
+      end
+
+      def list_tasks
+        result = rpc_call("tasks/list", {})
+        result.map { |t| Models::Task.from_hash(t) }
+      end
+
+      def cancel_task(task_id)
+        result = rpc_call("tasks/cancel", { "id" => task_id })
+        Models::Task.from_hash(result)
+      end
+
+      private
+
+      def rpc_call(method, params)
+        body = JSON.generate({
+          "jsonrpc" => "2.0",
+          "id"      => SecureRandom.uuid,
+          "method"  => method,
+          "params"  => params
+        })
+        resp_body = http_post(body)
+        parsed    = JSON.parse(resp_body)
+        raise A2A::Error, parsed["error"]["message"] if parsed["error"]
+
+        parsed["result"]
+      end
+
+      def http_post(body)
+        run_async do |internet|
+          internet.post(@url, headers: rpc_headers, body: body).read
+        end
+      end
+
+      def http_get(path)
+        url = [@url.chomp("/"), path].join("/")
+        run_async do |internet|
+          internet.get(url, headers: extra_headers).read
+        end
+      end
+
+      def run_async(&block)
+        if Async::Task.current?
+          with_internet(&block)
+        else
+          Async { with_internet(&block) }.wait
+        end
+      end
+
+      def with_internet
+        internet = Async::HTTP::Internet.new
+        yield internet
+      ensure
+        internet&.close
+      end
+
+      def rpc_headers
+        { "content-type" => "application/json" }.merge(extra_headers)
+      end
+
+      def extra_headers
+        @headers.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      def build_send_params(message, opts)
+        msg_hash = message.is_a?(Models::Message) ? message.to_h : message
+        params   = { "message" => msg_hash }
+        params["id"]        = opts[:task_id]    if opts[:task_id]
+        params["contextId"] = opts[:context_id] if opts[:context_id]
+        params["metadata"]  = opts[:metadata]   if opts[:metadata]
+        params
+      end
+    end
+  end
+end

data/lib/simple_a2a/client/sse.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module A2A
+  module Client
+    class SSE < Base
+      EVENT_CLASSES = {
+        "TaskStatusUpdateEvent"   => Models::TaskStatusUpdateEvent,
+        "TaskArtifactUpdateEvent" => Models::TaskArtifactUpdateEvent
+      }.freeze
+
+      def send_subscribe(message:, **opts, &block)
+        body = JSON.generate({
+          "jsonrpc" => "2.0",
+          "id"      => SecureRandom.uuid,
+          "method"  => "tasks/sendSubscribe",
+          "params"  => build_send_params(message, opts)
+        })
+
+        run_async do |internet|
+          headers  = rpc_headers.merge("accept" => "text/event-stream")
+          response = internet.post(@url, headers: headers, body: body)
+          parse_sse_stream(response, &block)
+        end
+      end
+
+      private
+
+      def parse_sse_stream(response, &block)
+        buffer = +""
+        response.body.each do |chunk|
+          buffer << chunk
+          while (idx = buffer.index("\n\n"))
+            event_str = buffer[0, idx]
+            buffer    = buffer[(idx + 2)..]
+            event     = parse_sse_event(event_str)
+            block.call(event) if event
+          end
+        end
+      end
+
+      def parse_sse_event(event_str)
+        data = nil
+        event_str.each_line do |line|
+          data = line.chomp[6..] if line.start_with?("data: ")
+        end
+        return nil unless data
+
+        parsed    = JSON.parse(data)
+        result    = parsed["result"] || parsed
+        type_name = result["type"] || result["kind"]
+        klass     = EVENT_CLASSES[type_name]
+        klass ? klass.from_hash(result) : result
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/simple_a2a/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class TaskNotFoundError < Error; end
+  class TaskNotCancelableError < Error; end
+  class PushNotificationNotSupportedError < Error; end
+  class UnsupportedOperationError < Error; end
+  class ContentTypeNotSupportedError < Error; end
+  class InvalidAgentResponseError < Error; end
+  class ExtensionSupportRequiredError < Error; end
+  class VersionNotSupportedError < Error; end
+  class ExtendedAgentCardNotConfiguredError < Error; end
+end

data/lib/simple_a2a/json_rpc.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module A2A
+  module JsonRpc
+    # A2A-defined JSON-RPC error codes
+    module ErrorCode
+      PARSE_ERROR             = -32700
+      INVALID_REQUEST         = -32600
+      METHOD_NOT_FOUND        = -32601
+      INVALID_PARAMS          = -32602
+      INTERNAL_ERROR          = -32603
+
+      TASK_NOT_FOUND          = -32001
+      TASK_NOT_CANCELABLE     = -32002
+      PUSH_NOT_SUPPORTED      = -32003
+      UNSUPPORTED_OPERATION   = -32004
+      CONTENT_TYPE_NOT_SUPPORTED = -32005
+      INVALID_AGENT_RESPONSE  = -32006
+      EXTENSION_REQUIRED      = -32007
+      VERSION_NOT_SUPPORTED   = -32008
+    end
+
+    class Request
+      attr_reader :id, :method, :params
+
+      def initialize(id:, method:, params: nil)
+        @id     = id
+        @method = method
+        @params = params
+      end
+
+      def self.parse(json_string)
+        data = JSON.parse(json_string)
+        raise ParseError, "not a Hash" unless data.is_a?(Hash)
+        raise InvalidRequestError, "missing jsonrpc field" unless data["jsonrpc"] == "2.0"
+        raise InvalidRequestError, "missing method"       unless data.key?("method")
+
+        new(
+          id:     data["id"],
+          method: data["method"],
+          params: data["params"]
+        )
+      rescue JSON::ParserError => e
+        raise ParseError, e.message
+      end
+
+      def notification? = id.nil?
+    end
+
+    class Response
+      def self.success(id:, result:)
+        JSON.generate({ "jsonrpc" => "2.0", "id" => id, "result" => result })
+      end
+
+      def self.error(id:, code:, message:, data: nil)
+        err = { "code" => code, "message" => message }
+        err["data"] = data if data
+        JSON.generate({ "jsonrpc" => "2.0", "id" => id, "error" => err })
+      end
+
+      def self.from_error(id:, error:)
+        code, msg = classify(error)
+        error(id: id, code: code, message: msg)
+      end
+
+      def self.classify(error)
+        case error
+        when TaskNotFoundError          then [ErrorCode::TASK_NOT_FOUND,       error.message || "Task not found"]
+        when TaskNotCancelableError     then [ErrorCode::TASK_NOT_CANCELABLE,   error.message || "Task not cancelable"]
+        when PushNotificationNotSupportedError then [ErrorCode::PUSH_NOT_SUPPORTED, error.message || "Push notifications not supported"]
+        when UnsupportedOperationError  then [ErrorCode::UNSUPPORTED_OPERATION, error.message || "Unsupported operation"]
+        when ContentTypeNotSupportedError then [ErrorCode::CONTENT_TYPE_NOT_SUPPORTED, error.message || "Content type not supported"]
+        when InvalidAgentResponseError  then [ErrorCode::INVALID_AGENT_RESPONSE, error.message || "Invalid agent response"]
+        when ExtensionSupportRequiredError then [ErrorCode::EXTENSION_REQUIRED, error.message || "Extension required"]
+        when VersionNotSupportedError   then [ErrorCode::VERSION_NOT_SUPPORTED, error.message || "Version not supported"]
+        when ParseError                 then [ErrorCode::PARSE_ERROR,           error.message || "Parse error"]
+        when InvalidRequestError        then [ErrorCode::INVALID_REQUEST,       error.message || "Invalid request"]
+        when InvalidParamsError         then [ErrorCode::INVALID_PARAMS,        error.message || "Invalid params"]
+        else                                 [ErrorCode::INTERNAL_ERROR,        error.message || "Internal error"]
+        end
+      end
+    end
+
+    # JSON-RPC specific errors (not A2A domain errors)
+    class ParseError        < A2A::Error; end
+    class InvalidRequestError < A2A::Error; end
+    class InvalidParamsError  < A2A::Error; end
+  end
+end

data/lib/simple_a2a/models/agent_capabilities.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class AgentCapabilities < Base
+      attribute :streaming,           default: false
+      attribute :push_notifications,  default: false
+      attribute :extended_agent_card, default: false
+    end
+  end
+end

data/lib/simple_a2a/models/agent_card.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class AgentCard < Base
+      attribute :name,             required: true
+      attribute :description
+      attribute :version,          required: true
+      attribute :provider,         type: AgentProvider
+      attribute :capabilities,     type: AgentCapabilities, required: true
+      attribute :skills,           type: [AgentSkill],      default: -> { [] }, required: true
+      attribute :interfaces,       type: [AgentInterface],  default: -> { [] }, required: true
+      attribute :security_schemes, default: -> { [] }
+      attribute :security,         default: -> { [] }
+      attribute :extensions,       default: -> { [] }
+
+      def valid?
+        !name.nil? && !version.nil? && !capabilities.nil? &&
+          !skills.nil? && !interfaces.nil?
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/agent_interface.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class AgentInterface < Base
+      attribute :type,    required: true
+      attribute :url,     required: true
+      attribute :version, required: true
+    end
+  end
+end

data/lib/simple_a2a/models/agent_provider.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class AgentProvider < Base
+      attribute :name, required: true
+      attribute :url
+      attribute :description
+    end
+  end
+end

data/lib/simple_a2a/models/agent_skill.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class AgentSkill < Base
+      attribute :name,         required: true
+      attribute :description
+      attribute :input_schema
+      attribute :output_schema
+    end
+  end
+end

data/lib/simple_a2a/models/artifact.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class Artifact < Base
+      attribute :artifact_id
+      attribute :name
+      attribute :description
+      attribute :parts,      type: [Part], default: -> { [] }
+      attribute :metadata
+      attribute :extensions, default: -> { [] }
+
+      def initialize(**kwargs)
+        kwargs[:artifact_id] ||= SecureRandom.uuid
+        super
+      end
+
+      def valid?
+        !parts.nil? && !parts.empty?
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/authentication_info.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class AuthenticationInfo < Base
+      attribute :scheme,      required: true
+      attribute :value,       required: true
+      attribute :header_name
+    end
+  end
+end

data/lib/simple_a2a/models/base.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class Base
+      class << self
+        def attribute(name, type: nil, default: nil, required: false)
+          attributes[name] = { type: type, default: default, required: required }
+          attr_accessor name
+        end
+
+        def attributes
+          @attributes ||= {}
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@attributes, attributes.dup)
+        end
+
+        def from_hash(hash)
+          return nil if hash.nil?
+          kwargs = {}
+          attributes.each do |name, opts|
+            val = find_value(hash, name)
+            next if val.nil?
+            kwargs[name] = coerce(val, opts[:type])
+          end
+          new(**kwargs)
+        end
+
+        private
+
+        def find_value(hash, name)
+          camel = camelize(name)
+          hash[camel] || hash[camel.to_sym] || hash[name.to_s] || hash[name]
+        end
+
+        def camelize(snake)
+          parts = snake.to_s.split("_")
+          (parts[0..0] + parts[1..].map(&:capitalize)).join
+        end
+
+        def coerce(val, type)
+          return val if type.nil?
+
+          if type.is_a?(Array)
+            item_type = type[0]
+            return val unless val.is_a?(Array)
+            return val.map { |v| coerce(v, item_type) }
+          end
+
+          return val if val.is_a?(type)
+          return type.from_hash(val) if val.is_a?(Hash) && type.respond_to?(:from_hash)
+          val
+        end
+      end
+
+      def initialize(**kwargs)
+        self.class.attributes.each do |name, opts|
+          val = kwargs.key?(name) ? kwargs[name] : resolve_default(opts[:default])
+          send(:"#{name}=", val)
+        end
+      end
+
+      def to_h
+        self.class.attributes.each_with_object({}) do |(name, _), result|
+          val = send(name)
+          next if val.nil?
+          result[camelize(name)] = serialize(val)
+        end
+      end
+
+      def to_json(*)
+        JSON.generate(to_h)
+      end
+
+      def valid?
+        self.class.attributes.all? do |name, opts|
+          !opts[:required] || !send(name).nil?
+        end
+      end
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        self.class.attributes.keys.all? { |n| send(n) == other.send(n) }
+      end
+
+      private
+
+      def camelize(snake)
+        parts = snake.to_s.split("_")
+        (parts[0..0] + parts[1..].map(&:capitalize)).join
+      end
+
+      def resolve_default(default)
+        default.respond_to?(:call) ? default.call : default
+      end
+
+      def serialize(val)
+        case val
+        when Base  then val.to_h
+        when Array then val.map { |v| serialize(v) }
+        when Hash  then val.transform_values { |v| serialize(v) }
+        when Time  then val.iso8601
+        else            val
+        end
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/message.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class Message < Base
+      attribute :message_id
+      attribute :role,               required: true
+      attribute :parts,              type: [Part], default: -> { [] }, required: true
+      attribute :context_id
+      attribute :task_id
+      attribute :reference_task_ids, default: -> { [] }
+      attribute :metadata
+      attribute :extensions,         default: -> { [] }
+
+      def self.user(*content)
+        new(message_id: SecureRandom.uuid, role: Types::Role::USER, parts: build_parts(content))
+      end
+
+      def self.agent(*content)
+        new(message_id: SecureRandom.uuid, role: Types::Role::AGENT, parts: build_parts(content))
+      end
+
+      def self.build_parts(content)
+        content.map { |c| c.is_a?(Part) ? c : Part.text(c.to_s) }
+      end
+      private_class_method :build_parts
+
+      def initialize(**kwargs)
+        kwargs[:message_id] ||= SecureRandom.uuid
+        super
+      end
+
+      def user?  = role == Types::Role::USER
+      def agent? = role == Types::Role::AGENT
+
+      def text_content
+        parts.select(&:text?).map(&:text).join("\n")
+      end
+
+      def valid?
+        !role.nil? && !parts.nil? && !parts.empty?
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/part.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class Part < Base
+      attribute :text
+      attribute :raw
+      attribute :url
+      attribute :data
+      attribute :media_type
+      attribute :filename
+      attribute :metadata
+
+      def self.text(content, media_type: "text/plain", filename: nil)
+        new(text: content, media_type: media_type, filename: filename)
+      end
+
+      def self.json(hash, filename: nil)
+        new(data: hash, media_type: "application/json", filename: filename)
+      end
+
+      def self.from_url(url, media_type:, filename: nil)
+        new(url: url, media_type: media_type, filename: filename)
+      end
+
+      def self.binary(bytes, media_type:, filename: nil)
+        new(raw: Base64.strict_encode64(bytes), media_type: media_type, filename: filename)
+      end
+
+      def text?  = !text.nil?
+      def json?  = !data.nil?
+      def url?   = !url.nil?
+      def raw?   = !raw.nil?
+
+      def decoded_bytes
+        return nil unless raw
+        Base64.strict_decode64(raw)
+      end
+
+      def valid?
+        [text, raw, url, data].compact.length == 1
+      end
+    end
+  end
+end