a2a-rb 0.1.1

data/lib/a2a/agent_card.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "agent_card/signature"
+require_relative "agent_card/verifier"
+require_relative "agent_card/builder"
+
+module A2A
+  class AgentCard
+    attr_reader :name, :description, :supported_interfaces, :provider, :version,
+                :documentation_url, :capabilities, :security_schemes, :security_requirements,
+                :default_input_modes, :default_output_modes, :skills, :signatures, :icon_url
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def initialize(name:, description:, **kwargs)
+      supported_interfaces = kwargs.fetch(:supported_interfaces)
+      default_input_modes = kwargs.fetch(:default_input_modes)
+      default_output_modes = kwargs.fetch(:default_output_modes)
+      skills = kwargs.fetch(:skills)
+
+      validate_required_collections!(supported_interfaces, default_input_modes, default_output_modes, skills)
+
+      @name = name
+      @description = description
+      @supported_interfaces = supported_interfaces
+      @version = kwargs.fetch(:version)
+      @capabilities = kwargs.fetch(:capabilities)
+      @default_input_modes = default_input_modes
+      @default_output_modes = default_output_modes
+      @skills = skills
+      @provider = kwargs.fetch(:provider, nil)
+      @documentation_url = kwargs.fetch(:documentation_url, nil)
+      @security_schemes = kwargs.fetch(:security_schemes, nil)
+      @security_requirements = kwargs.fetch(:security_requirements, nil)
+      @signatures = kwargs.fetch(:signatures, nil)
+      @icon_url = kwargs.fetch(:icon_url, nil)
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def self.from_h(hash)
+      new(
+        name: hash.fetch("name"),
+        description: hash.fetch("description"),
+        version: hash.fetch("version"),
+        supported_interfaces: hash.fetch("supportedInterfaces").map { AgentInterface.from_h(_1) },
+        capabilities: AgentCapabilities.from_h(hash.fetch("capabilities")),
+        skills: hash.fetch("skills").map { AgentSkill.from_h(_1) },
+        security_schemes: (hash["securitySchemes"] || {}).transform_values { SecurityScheme.from_h(_1) },
+        security_requirements: hash["security"],
+        default_input_modes: hash.fetch("defaultInputModes"),
+        default_output_modes: hash.fetch("defaultOutputModes"),
+        provider: hash["provider"] && AgentProvider.from_h(hash["provider"]),
+        documentation_url: hash["documentationUrl"],
+        icon_url: hash["iconUrl"],
+        signatures: hash["signatures"]&.map { Signature.from_h(_1) }
+      )
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def to_h
+      required_fields.merge(optional_fields).compact
+    end
+
+    # §8.4.1 — RFC 8785 canonical JSON: to_h with "signatures" excluded and
+    # keys sorted recursively. Used as the payload for JWS signing/verification.
+    def canonical_json
+      JSON.generate(sort_keys_recursive(to_h.except("signatures")))
+    end
+
+    # §5.2 — returns the first interface whose protocolBinding the caller supports,
+    # preserving the agent's declared preference order (index 0 = most preferred).
+    def preferred_interface(preference: [AgentInterface::JSONRPC, AgentInterface::HTTP_JSON])
+      supported_interfaces.find { |i| preference.include?(i.protocol_binding) }
+    end
+
+    private
+
+    def validate_required_collections!(interfaces, input_modes, output_modes, skills)
+      raise ArgumentError, "supported_interfaces must contain at least one element" if Array(interfaces).empty?
+      raise ArgumentError, "skills must contain at least one element" if Array(skills).empty?
+      raise ArgumentError, "default_input_modes must contain at least one element" if Array(input_modes).empty?
+      raise ArgumentError, "default_output_modes must contain at least one element" if Array(output_modes).empty?
+    end
+
+    def required_fields
+      {
+        "name" => name,
+        "description" => description,
+        "version" => version,
+        "supportedInterfaces" => supported_interfaces.map(&:to_h),
+        "capabilities" => capabilities.to_h,
+        "skills" => skills.map(&:to_h),
+        "defaultInputModes" => default_input_modes,
+        "defaultOutputModes" => default_output_modes
+      }
+    end
+
+    def optional_fields
+      {
+        "provider" => provider&.to_h,
+        "documentationUrl" => documentation_url,
+        "iconUrl" => icon_url,
+        "securitySchemes" => security_schemes&.transform_values(&:to_h),
+        "security" => security_requirements,
+        "signatures" => signatures&.map(&:to_h)
+      }
+    end
+
+    def sort_keys_recursive(obj)
+      case obj
+      when Hash then obj.sort.to_h.transform_values { sort_keys_recursive(_1) }
+      when Array then obj.map { sort_keys_recursive(_1) }
+      else obj
+      end
+    end
+  end
+end

data/lib/a2a/agent_extension.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentExtension
+    attr_reader :uri, :description, :required, :params
+
+    def initialize(uri: nil, description: nil, required: nil, params: nil)
+      @uri = uri
+      @description = description
+      @required = required
+      @params = params
+    end
+
+    def self.from_h(hash)
+      new(
+        uri: hash["uri"],
+        description: hash["description"],
+        required: hash["required"],
+        params: hash["params"]
+      )
+    end
+
+    def to_h
+      {
+        "uri" => uri,
+        "description" => description,
+        "required" => required,
+        "params" => params
+      }.compact
+    end
+  end
+end

data/lib/a2a/agent_interface.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentInterface
+    attr_reader :url, :protocol_binding, :protocol_version, :tenant
+
+    JSONRPC = "JSONRPC"
+    GRPC = "GRPC"
+    HTTP_JSON = "HTTP+JSON"
+
+    VALID_BINDINGS = [JSONRPC, GRPC, HTTP_JSON].freeze
+
+    def initialize(url:, protocol_binding:, protocol_version:, tenant: nil)
+      unless VALID_BINDINGS.include?(protocol_binding)
+        raise ArgumentError, "protocol_binding must be one of #{VALID_BINDINGS.join(', ')}"
+      end
+
+      @url = url
+      @protocol_binding = protocol_binding
+      @protocol_version = protocol_version
+      @tenant = tenant
+    end
+
+    def self.from_h(hash)
+      new(
+        url: hash.fetch("url"),
+        protocol_binding: hash.fetch("protocolBinding"),
+        protocol_version: hash.fetch("protocolVersion"),
+        tenant: hash["tenant"]
+      )
+    end
+
+    def to_h
+      {
+        "url" => url,
+        "protocolBinding" => protocol_binding,
+        "protocolVersion" => protocol_version,
+        "tenant" => tenant
+      }.compact
+    end
+
+    def json_rpc?
+      protocol_binding == JSONRPC
+    end
+
+    def grpc?
+      protocol_binding == GRPC
+    end
+
+    def http_json?
+      protocol_binding == HTTP_JSON
+    end
+  end
+end

data/lib/a2a/agent_provider.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentProvider
+    attr_reader :organization, :url
+
+    def initialize(organization:, url:)
+      @organization = organization
+      @url = url
+    end
+
+    def self.from_h(hash)
+      new(organization: hash.fetch("organization"), url: hash.fetch("url"))
+    end
+
+    def to_h
+      { "organization" => organization, "url" => url }
+    end
+  end
+end

data/lib/a2a/agent_skill.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentSkill
+    attr_reader :id, :name, :description, :tags, :examples, :input_modes, :output_modes, :security_requirements
+
+    def initialize(id:, name:, description:, tags:, **kwargs)
+      raise ArgumentError, "tags must contain at least one element" if Array(tags).empty?
+
+      @id = id
+      @name = name
+      @description = description
+      @tags = tags
+      @examples = kwargs[:examples]
+      @input_modes = kwargs[:input_modes]
+      @output_modes = kwargs[:output_modes]
+      @security_requirements = kwargs[:security_requirements]
+    end
+
+    def self.from_h(hash)
+      new(
+        id: hash.fetch("id"),
+        name: hash.fetch("name"),
+        description: hash.fetch("description"),
+        tags: hash.fetch("tags"),
+        examples: hash["examples"],
+        input_modes: hash["inputModes"],
+        output_modes: hash["outputModes"],
+        security_requirements: hash["securityRequirements"]&.map { SecurityRequirement.from_h(_1) }
+      )
+    end
+
+    def to_h
+      {
+        "id" => id,
+        "name" => name,
+        "description" => description,
+        "tags" => tags,
+        "examples" => examples,
+        "inputModes" => input_modes,
+        "outputModes" => output_modes,
+        "securityRequirements" => security_requirements&.map(&:to_h)
+      }.compact
+    end
+  end
+end

data/lib/a2a/artifact.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module A2A
+  class Artifact
+    attr_reader :id, :name, :description, :parts, :extensions, :metadata
+
+    def initialize(id:, parts:, **kwargs)
+      raise ArgumentError, "parts must contain at least one element" if Array(parts).empty?
+
+      @id = id
+      @parts = parts
+      @name = kwargs[:name]
+      @description = kwargs[:description]
+      @extensions = kwargs[:extensions]
+      @metadata = kwargs[:metadata]
+    end
+
+    def self.from_h(hash)
+      new(
+        id: hash.fetch("artifactId"),
+        name: hash["name"],
+        description: hash["description"],
+        parts: Array(hash["parts"]).map { Part.from_h(_1) },
+        extensions: hash["extensions"],
+        metadata: hash["metadata"]
+      )
+    end
+
+    def to_h
+      {
+        "parts" => parts.map(&:to_h),
+        "artifactId" => id,
+        "name" => name,
+        "description" => description,
+        "extensions" => extensions,
+        "metadata" => metadata
+      }.compact
+    end
+  end
+end

data/lib/a2a/client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module A2A
+  class Client
+    SUPPORTED_BINDINGS = [AgentInterface::JSONRPC, AgentInterface::HTTP_JSON].freeze
+
+    # §5.2, §8.3.2 — constructs a Client from an AgentCard by negotiating the
+    # protocol binding. The agent's supportedInterfaces order is respected:
+    # the first interface whose protocolBinding appears in `preference` wins.
+    def self.from_agent_card(card, headers: {}, extensions: [], preference: SUPPORTED_BINDINGS)
+      iface = card.preferred_interface(preference: preference)
+
+      unless iface
+        found = card.supported_interfaces.map(&:protocol_binding).join(", ")
+        raise UnsupportedOperationError, "no supported interface in agent card (available: #{found})"
+      end
+
+      Versioning.validate!(iface.protocol_version)
+
+      protocol = build_protocol(iface, headers: headers, extensions: extensions)
+      new(protocol: protocol, capabilities: card.capabilities)
+    end
+
+    def self.build_protocol(iface, headers:, extensions:)
+      klass = iface.protocol_binding == AgentInterface::JSONRPC ? Protocol::JsonRpc : Protocol::HttpJson
+      klass.new(url: iface.url, version: iface.protocol_version, headers: headers, extensions: extensions)
+    end
+
+    private_class_method :build_protocol
+
+    def initialize(protocol:, capabilities: nil)
+      @protocol = protocol
+      @capabilities = capabilities
+    end
+
+    def send_message(message, configuration: {}, metadata: nil, tenant: nil)
+      run Operation::SendMessage.new(message, configuration: configuration, metadata: metadata, tenant: tenant)
+    end
+
+    def send_streaming_message(message, configuration: {}, metadata: nil, tenant: nil, &block)
+      op = Operation::SendStreamingMessage.new(message, configuration: configuration, metadata: metadata, tenant: tenant)
+      run op, &block
+    end
+
+    def get_task(id, history_length: nil, tenant: nil)
+      run Operation::GetTask.new(id:, history_length:, tenant:)
+    end
+
+    def list_tasks(**kwargs)
+      run Operation::ListTasks.new(**kwargs)
+    end
+
+    def cancel_task(id, metadata: nil, tenant: nil)
+      if id.is_a?(Task) && id.terminal?
+        raise TaskNotCancelableError, "task #{id.id} is already in a terminal state (#{id.status.state})"
+      end
+
+      task_id = id.is_a?(Task) ? id.id : id
+      run Operation::CancelTask.new(id: task_id, metadata:, tenant:)
+    end
+
+    def subscribe_to_task(id, tenant: nil, &block)
+      run Operation::SubscribeToTask.new(id:, tenant:), &block
+    end
+
+    def create_task_push_notification_config(config, tenant: nil)
+      require_push_notifications!
+      run Operation::CreateTaskPushNotificationConfig.new(config, tenant:)
+    end
+
+    def get_task_push_notification_config(task_id:, id:, tenant: nil)
+      require_push_notifications!
+      run Operation::GetTaskPushNotificationConfig.new(task_id:, id:, tenant:)
+    end
+
+    def list_task_push_notification_configs(task_id:, page_size: nil, page_token: nil, tenant: nil)
+      require_push_notifications!
+      run Operation::ListTaskPushNotificationConfigs.new(task_id:, page_size:, page_token:, tenant:)
+    end
+
+    def delete_task_push_notification_config(task_id:, id:, tenant: nil)
+      require_push_notifications!
+      run Operation::DeleteTaskPushNotificationConfig.new(task_id:, id:, tenant:)
+    end
+
+    def get_extended_agent_card(tenant: nil)
+      require_extended_agent_card!
+      run Operation::GetExtendedAgentCard.new(tenant:)
+    end
+
+    private
+
+    def require_push_notifications!
+      return unless @capabilities&.push_notifications == false
+
+      raise PushNotificationNotSupportedError, "agent does not support push notifications"
+    end
+
+    def require_extended_agent_card!
+      return unless @capabilities&.extended_agent_card == false
+
+      raise ExtendedAgentCardNotConfiguredError, "agent does not support extended agent card"
+    end
+
+    def run(operation, &)
+      operation.execute(@protocol, &)
+    end
+  end
+end

data/lib/a2a/discovery.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module A2A
+  module Discovery
+    WELL_KNOWN_PATH = "/.well-known/agent-card.json"
+
+    # §8.2, §14.3 — fetches the public AgentCard from /.well-known/a2a.
+    # No authentication required.
+    def self.fetch(base_url, transport: Transport.new)
+      url = "#{base_url.chomp('/')}#{WELL_KNOWN_PATH}"
+      AgentCard.from_h(transport.get(url))
+    end
+
+    # §8.6.2 — fetches the public card, then calls GetExtendedAgentCard.
+    # The public card must declare capabilities.extendedAgentCard: true.
+    def self.fetch_extended(base_url, headers: {}, extensions: [], transport: Transport.new)
+      card = fetch(base_url, transport: transport)
+      Client.from_agent_card(card, headers: headers, extensions: extensions)
+            .get_extended_agent_card
+    end
+
+    class Transport
+      def get(url)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        response = http.request(Net::HTTP::Get.new(uri.request_uri,
+                                                   "Accept" => "application/json"))
+        handle(response)
+      end
+
+      private
+
+      def handle(response)
+        case response.code.to_i
+        when 200..299 then JSON.parse(response.body)
+        when 401 then raise AuthenticationError, "HTTP 401"
+        when 403 then raise AuthorizationError, "HTTP 403"
+        when 404 then raise TransportError, "agent card not found (HTTP 404)"
+        else raise TransportError, "HTTP #{response.code}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/json_rpc_envelope.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module A2A
+  module JSONRPCEnvelope
+    # Builds a success response envelope.
+    def self.success(id:, result:)
+      { "jsonrpc" => "2.0", "id" => id, "result" => result }
+    end
+
+    # Builds an error response envelope from an A2A::Error or any StandardError.
+    # If the error carries a numeric code it is used directly; otherwise falls
+    # back to -32603 (InternalError).
+    def self.error(id:, error:)
+      code = error.respond_to?(:code) && error.code ? error.code : -32603
+      {
+        "jsonrpc" => "2.0",
+        "id" => id,
+        "error" => { "code" => code, "message" => error.message }
+      }
+    end
+
+    # Parses the JSON-RPC id and method from a raw request hash.
+    def self.parse_request(hash)
+      id = hash["id"]
+      method = hash["method"]
+      params = hash["params"] || {}
+      raise InvalidRequestError, "missing method" unless method
+
+      [id, method, params]
+    end
+  end
+end

data/lib/a2a/message.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module A2A
+  class Message
+    attr_reader :id, :role, :parts,
+                :context_id, :task_id,
+                :reference_task_ids, :extensions, :metadata
+
+    def initialize(id:, role:, parts:, **kwargs)
+      raise ArgumentError, "invalid role: #{role.inspect}" unless Role.valid?(role)
+      raise ArgumentError, "parts must contain at least one element" if Array(parts).empty?
+
+      @id = id
+      @role = role
+      @parts = parts
+      @context_id = kwargs[:context_id]
+      @task_id = kwargs[:task_id]
+      @reference_task_ids = kwargs[:reference_task_ids]
+      @extensions = kwargs[:extensions]
+      @metadata = kwargs[:metadata]
+    end
+
+    def self.from_h(hash)
+      new(
+        id: hash.fetch("messageId"),
+        role: hash.fetch("role"),
+        parts: Array(hash["parts"]).map { Part.from_h(_1) },
+        context_id: hash["contextId"],
+        task_id: hash["taskId"],
+        reference_task_ids: hash["referenceTaskIds"],
+        extensions: hash["extensions"],
+        metadata: hash["metadata"]
+      )
+    end
+
+    def to_h
+      {
+        "messageId" => id,
+        "role" => role,
+        "parts" => parts.map(&:to_h),
+        "contextId" => context_id,
+        "taskId" => task_id,
+        "metadata" => metadata,
+        "referenceTaskIds" => reference_task_ids,
+        "extensions" => extensions
+      }.compact
+    end
+
+    # Returns the plain-text content of the first Parts::Text, or nil.
+    def text
+      parts.find { |p| p.is_a?(Part::Text) }&.text
+    end
+  end
+end

data/lib/a2a/oauth_flow/authorization_code.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module A2A
+  module OAuthFlow
+    class AuthorizationCode
+      attr_reader :authorization_url, :token_url, :refresh_url, :scopes, :pkce_required
+
+      def initialize(authorization_url:, token_url:, scopes:, refresh_url: nil, pkce_required: nil)
+        @authorization_url = authorization_url
+        @token_url = token_url
+        @scopes = scopes
+        @refresh_url = refresh_url
+        @pkce_required = pkce_required
+      end
+
+      def self.from_h(hash)
+        new(
+          authorization_url: hash.fetch("authorizationUrl"),
+          scopes: hash.fetch("scopes"),
+          token_url: hash.fetch("tokenUrl"),
+          refresh_url: hash["refreshUrl"],
+          pkce_required: hash["pkceRequired"]
+        )
+      end
+
+      def to_h
+        {
+          "authorizationUrl" => authorization_url,
+          "tokenUrl" => token_url,
+          "scopes" => scopes,
+          "refreshUrl" => refresh_url,
+          "pkceRequired" => pkce_required
+        }.compact
+      end
+    end
+  end
+end

data/lib/a2a/oauth_flow/client_credentials.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module A2A
+  module OAuthFlow
+    class ClientCredentials
+      attr_reader :token_url, :refresh_url, :scopes
+
+      def initialize(token_url:, scopes:, refresh_url: nil)
+        @token_url = token_url
+        @scopes = scopes
+        @refresh_url = refresh_url
+      end
+
+      def self.from_h(hash)
+        new(
+          scopes: hash.fetch("scopes"),
+          token_url: hash.fetch("tokenUrl"),
+          refresh_url: hash["refreshUrl"]
+        )
+      end
+
+      def to_h
+        {
+          "tokenUrl" => token_url,
+          "scopes" => scopes,
+          "refreshUrl" => refresh_url
+        }.compact
+      end
+    end
+  end
+end

data/lib/a2a/oauth_flow/device_code.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module A2A
+  module OAuthFlow
+    class DeviceCode
+      attr_reader :device_authorization_url, :token_url, :refresh_url, :scopes
+
+      def initialize(device_authorization_url:, token_url:, scopes:, refresh_url: nil)
+        @device_authorization_url = device_authorization_url
+        @token_url = token_url
+        @scopes = scopes
+        @refresh_url = refresh_url
+      end
+
+      def self.from_h(hash)
+        new(
+          device_authorization_url: hash.fetch("deviceAuthorizationUrl"),
+          scopes: hash.fetch("scopes"),
+          token_url: hash.fetch("tokenUrl"),
+          refresh_url: hash["refreshUrl"]
+        )
+      end
+
+      def to_h
+        {
+          "deviceAuthorizationUrl" => device_authorization_url,
+          "tokenUrl" => token_url,
+          "scopes" => scopes,
+          "refreshUrl" => refresh_url
+        }.compact
+      end
+    end
+  end
+end