a2a-rails 0.1.0

data/lib/a2a/rails/agent.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Agent
+      UNSET = Object.new.freeze
+
+      class << self
+        def name(value = UNSET)
+          return super() if value.equal?(UNSET)
+
+          @a2a_name = value
+        end
+
+        def agent_name
+          @a2a_name
+        end
+
+        def description(value = UNSET)
+          return @a2a_description if value.equal?(UNSET)
+
+          @a2a_description = value
+        end
+
+        def version(value = UNSET)
+          return @a2a_version if value.equal?(UNSET)
+
+          @a2a_version = value
+        end
+
+        def router(value = UNSET)
+          return @a2a_router if value.equal?(UNSET)
+
+          @a2a_router = value
+        end
+
+        def skill(id, description:, tags:, handler:, name: nil, examples: nil, input_modes: nil, output_modes: nil)
+          definition = Skill.new(
+            id: id,
+            name: name,
+            description: description,
+            tags: tags,
+            handler: handler,
+            examples: examples,
+            input_modes: input_modes,
+            output_modes: output_modes
+          )
+          skill_definitions << definition
+          definition
+        end
+
+        def skills
+          skill_definitions.dup.freeze
+        end
+
+        def validate!
+          validate_metadata!
+          validate_skills!
+          validate_router!
+          self
+        end
+
+        private
+
+        def skill_definitions
+          @a2a_skills ||= []
+        end
+
+        def validate_metadata!
+          {
+            name: @a2a_name,
+            description: @a2a_description,
+            version: @a2a_version
+          }.each do |field, value|
+            next unless value.nil? || value.to_s.strip.empty?
+
+            raise ConfigurationError, "#{self} must define #{field}"
+          end
+        end
+
+        def validate_skills!
+          if skill_definitions.empty?
+            raise ConfigurationError, "#{self} must define at least one skill"
+          end
+
+          duplicate = skill_definitions.group_by(&:id).find { |_id, definitions| definitions.length > 1 }
+          if duplicate
+            raise ConfigurationError, "#{self} defines duplicate skill id: #{duplicate.first.inspect}"
+          end
+
+          skill_definitions.each(&:validate!)
+        end
+
+        def validate_router!
+          if skill_definitions.length > 1 && @a2a_router.nil?
+            raise ConfigurationError, "#{self} defines multiple skills but no Router is configured"
+          end
+
+          return if @a2a_router.nil? || @a2a_router.respond_to?(:call)
+
+          raise ConfigurationError, "Router #{@a2a_router.inspect} must respond to .call"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/agent_card/builder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module A2A
+  module Rails
+    module AgentCard
+      class Builder
+        DEFAULT_INPUT_MODES = ["text/plain"].freeze
+        DEFAULT_OUTPUT_MODES = ["text/plain"].freeze
+
+        def initialize(agent:, public_base_url: nil, request_base_url: nil, validator: Validator.new)
+          @agent = agent
+          @public_base_url = public_base_url
+          @request_base_url = request_base_url
+          @validator = validator
+        end
+
+        def call
+          @agent.validate!
+
+          card = {
+            "name" => @agent.agent_name.to_s,
+            "description" => @agent.description.to_s,
+            "version" => @agent.version.to_s,
+            "supportedInterfaces" => [
+              {
+                "url" => endpoint_url,
+                "protocolBinding" => "JSONRPC",
+                "protocolVersion" => "1.0"
+              }
+            ],
+            "capabilities" => {
+              "streaming" => false,
+              "pushNotifications" => false,
+              "extendedAgentCard" => false
+            },
+            "defaultInputModes" => DEFAULT_INPUT_MODES.dup,
+            "defaultOutputModes" => DEFAULT_OUTPUT_MODES.dup,
+            "skills" => @agent.skills.map { |skill| skill_hash(skill) }
+          }
+
+          @validator.validate!(card)
+        end
+
+        private
+
+        def endpoint_url
+          base = @public_base_url
+          base = @request_base_url if base.nil? || base.to_s.strip.empty?
+          if base.nil? || base.to_s.strip.empty?
+            raise ConfigurationError, "Agent Card requires public_base_url or request_base_url"
+          end
+
+          normalized = normalize_base_url(base.to_s)
+          "#{normalized}/a2a"
+        end
+
+        def normalize_base_url(value)
+          uri = URI.parse(value.strip)
+          unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty?
+            raise ConfigurationError, "Agent Card base URL must be an absolute HTTP(S) URL"
+          end
+
+          if uri.userinfo || uri.query || uri.fragment
+            raise ConfigurationError, "Agent Card base URL must not contain userinfo, query, or fragment"
+          end
+
+          segments = uri.path.to_s.split("/").reject(&:empty?)
+          if segments.include?("a2a")
+            raise ConfigurationError, "Agent Card base URL must not contain /a2a"
+          end
+
+          uri.path = uri.path.to_s.sub(%r{/+\z}, "")
+          uri.to_s.sub(%r{/+\z}, "")
+        rescue URI::InvalidURIError
+          raise ConfigurationError, "Agent Card base URL must be an absolute HTTP(S) URL"
+        end
+
+        def skill_hash(skill)
+          data = {
+            "id" => skill.id.to_s,
+            "name" => skill.name,
+            "description" => skill.description,
+            "tags" => skill.tags.dup
+          }
+          data["examples"] = skill.examples.dup unless skill.examples.nil?
+          data["inputModes"] = skill.input_modes.dup unless skill.input_modes.nil?
+          data["outputModes"] = skill.output_modes.dup unless skill.output_modes.nil?
+          data
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/agent_card/validator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module A2A
+  module Rails
+    module AgentCard
+      class Validator
+        def validate!(card)
+          unless card.is_a?(Hash)
+            raise ConfigurationError, "Agent Card must be a Hash"
+          end
+
+          validate_text!(card, "name")
+          validate_text!(card, "description")
+          validate_text!(card, "version")
+          validate_interfaces!(card["supportedInterfaces"])
+          validate_capabilities!(card["capabilities"])
+          validate_string_array!(card["defaultInputModes"], "defaultInputModes", allow_empty: false)
+          validate_string_array!(card["defaultOutputModes"], "defaultOutputModes", allow_empty: false)
+          validate_skills!(card["skills"])
+          card
+        end
+
+        private
+
+        def validate_text!(hash, key)
+          value = hash[key]
+          return if value.is_a?(String) && !value.strip.empty?
+
+          raise ConfigurationError, "Agent Card #{key} must be a non-empty String"
+        end
+
+        def validate_interfaces!(interfaces)
+          unless interfaces.is_a?(Array) && !interfaces.empty?
+            raise ConfigurationError, "Agent Card supportedInterfaces must contain at least one interface"
+          end
+
+          interfaces.each do |interface|
+            unless interface.is_a?(Hash)
+              raise ConfigurationError, "Agent Card interface must be a Hash"
+            end
+
+            validate_http_url!(interface["url"])
+            unless interface["protocolBinding"] == "JSONRPC" && interface["protocolVersion"] == "1.0"
+              raise ConfigurationError, "Agent Card v0.1 interface must use JSONRPC protocol version 1.0"
+            end
+          end
+        end
+
+        def validate_http_url!(value)
+          uri = URI.parse(value.to_s)
+          return if %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty? && uri.query.nil? && uri.fragment.nil?
+
+          raise ConfigurationError, "Agent Card interface URL must be an absolute HTTP(S) URL"
+        rescue URI::InvalidURIError
+          raise ConfigurationError, "Agent Card interface URL must be an absolute HTTP(S) URL"
+        end
+
+        def validate_capabilities!(capabilities)
+          unless capabilities.is_a?(Hash)
+            raise ConfigurationError, "Agent Card capabilities must be a Hash"
+          end
+
+          %w[streaming pushNotifications extendedAgentCard].each do |key|
+            unless capabilities[key] == false
+              raise ConfigurationError, "Agent Card v0.1 capability #{key} must be false"
+            end
+          end
+        end
+
+        def validate_skills!(skills)
+          unless skills.is_a?(Array) && !skills.empty?
+            raise ConfigurationError, "Agent Card skills must contain at least one Skill"
+          end
+
+          ids = skills.map do |skill|
+            unless skill.is_a?(Hash)
+              raise ConfigurationError, "Agent Card Skill must be a Hash"
+            end
+
+            if skill.key?("handler") || skill.key?(:handler)
+              raise ConfigurationError, "Agent Card must not expose Handler internals"
+            end
+
+            %w[id name description].each { |key| validate_text!(skill, key) }
+            validate_string_array!(skill["tags"], "Skill tags", allow_empty: false)
+            validate_string_array!(skill["examples"], "Skill examples", allow_empty: true) if skill.key?("examples")
+            validate_string_array!(skill["inputModes"], "Skill inputModes", allow_empty: false) if skill.key?("inputModes")
+            validate_string_array!(skill["outputModes"], "Skill outputModes", allow_empty: false) if skill.key?("outputModes")
+            skill["id"]
+          end
+
+          duplicate = ids.group_by(&:itself).find { |_id, matches| matches.length > 1 }
+          raise ConfigurationError, "Agent Card defines duplicate Skill id: #{duplicate.first}" if duplicate
+        end
+
+        def validate_string_array!(value, label, allow_empty:)
+          valid = value.is_a?(Array) &&
+            (allow_empty || !value.empty?) &&
+            value.all? { |entry| entry.is_a?(String) && !entry.strip.empty? }
+          return if valid
+
+          raise ConfigurationError, "Agent Card #{label} must be an Array of non-empty Strings"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module A2A
+  module Rails
+    class Configuration
+      attr_accessor :agent, :public_base_url
+
+      def initialize
+        @agent = nil
+        @public_base_url = nil
+        @logger_set = false
+      end
+
+      def logger
+        return @logger if @logger_set
+        return ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+
+        nil
+      end
+
+      def logger=(value)
+        @logger_set = true
+        @logger = value
+      end
+
+      def validate!
+        validate_agent_name!
+        normalized_public_base_url
+        self
+      end
+
+      def resolve_agent
+        validate_agent_name!
+
+        resolved = constantize(@agent.strip)
+        unless resolved.is_a?(Class) && resolved <= A2A::Rails::Agent
+          raise ConfigurationError, "Configured agent must inherit from A2A::Rails::Agent"
+        end
+
+        resolved.validate!
+        resolved
+      rescue NameError
+        raise ConfigurationError, "Configured agent could not be resolved"
+      end
+
+      def normalized_public_base_url
+        value = @public_base_url
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        normalize_base_url(value.to_s)
+      end
+
+      private
+
+      def validate_agent_name!
+        unless @agent.is_a?(String) && !@agent.strip.empty?
+          raise ConfigurationError, "config.agent must be a non-empty class-name String"
+        end
+
+        parts = @agent.strip.sub(/\A::/, "").split("::")
+        unless parts.all? { |part| part.match?(/\A[A-Z]\w*\z/) }
+          raise ConfigurationError, "config.agent must be a valid class-name String"
+        end
+      end
+
+      def constantize(name)
+        name.sub(/\A::/, "").split("::").reduce(Object) do |namespace, constant_name|
+          namespace.const_get(constant_name, false)
+        end
+      end
+
+      def normalize_base_url(value)
+        uri = URI.parse(value.strip)
+        unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty?
+          raise ConfigurationError, "config.public_base_url must be an absolute HTTP(S) URL"
+        end
+
+        if uri.userinfo || uri.query || uri.fragment
+          raise ConfigurationError, "config.public_base_url must not contain userinfo, query, or fragment"
+        end
+
+        segments = uri.path.to_s.split("/").reject(&:empty?)
+        if segments.include?("a2a")
+          raise ConfigurationError, "config.public_base_url must not contain /a2a"
+        end
+
+        uri.path = uri.path.to_s.sub(%r{/+\z}, "")
+        uri.to_s.sub(%r{/+\z}, "")
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "config.public_base_url must be an absolute HTTP(S) URL"
+      end
+    end
+  end
+end

data/lib/a2a/rails/dispatcher.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Dispatcher
+      def initialize(agent:)
+        @agent = agent
+      end
+
+      def validate!
+        @agent.validate!
+        self
+      end
+
+      def call(message:, context:)
+        validate!
+        skill = select_skill(message: message, context: context)
+        handler_context = context.merge(skill_id: skill.id)
+
+        skill.handler.call(message: message, context: handler_context)
+      end
+
+      private
+
+      def select_skill(message:, context:)
+        declared = @agent.skills
+        return declared.first if declared.one?
+
+        selected = @agent.router.call(
+          message: message,
+          context: context,
+          skills: declared.map(&:id).freeze
+        )
+        selected_id = normalize_selected_id(selected)
+
+        declared.find { |skill| skill.id == selected_id } ||
+          raise(UnknownSkillError, "Router selected unknown skill: #{selected.inspect}")
+      end
+
+      def normalize_selected_id(value)
+        value.to_sym
+      rescue NoMethodError
+        raise UnknownSkillError, "Router selected unknown skill: #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/a2a/rails/engine.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module/delegation"
+require "action_dispatch"
+require "action_controller/api"
+require "rails/engine"
+require_relative "../../../app/controllers/a2a/rails/application_controller"
+require_relative "../../../app/controllers/a2a/rails/agent_cards_controller"
+require_relative "../../../app/controllers/a2a/rails/requests_controller"
+
+module A2A
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace A2A::Rails
+
+      initializer "a2a-rails.mount_engine" do |app|
+        app.routes.append do
+          mount A2A::Rails::Engine => "/"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Error < StandardError; end
+
+    class ConfigurationError < Error; end
+    class InvalidHandlerError < ConfigurationError; end
+    class UnknownSkillError < ConfigurationError; end
+
+    class RejectedTask < Error; end
+    class ArtifactMappingError < Error; end
+
+    class ProtocolError < Error; end
+    class InvalidRequestError < ProtocolError; end
+    class ContentTypeNotSupportedError < ProtocolError; end
+    class TaskContinuationNotSupportedError < ProtocolError; end
+
+    class TaskError < Error; end
+    class TaskNotFoundError < TaskError
+      attr_reader :task_id
+
+      def initialize(task_id)
+        @task_id = task_id
+        super("Task not found: #{task_id}")
+      end
+    end
+
+    class TaskNotCancelableError < TaskError
+      attr_reader :task_id, :state
+
+      def initialize(task_id, state:)
+        @task_id = task_id
+        @state = state
+        super("Task #{task_id} is not cancelable from #{state}")
+      end
+    end
+
+    class InvalidTaskQueryError < TaskError; end
+    class InvalidTaskStateError < TaskError; end
+  end
+end

data/lib/a2a/rails/protocol/adapter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module Protocol
+      class Adapter
+        def call(_env)
+          raise NotImplementedError, "Protocol adapters must implement #call"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/protocol/agent2agent_adapter.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "a2a"
+require "rack"
+require "stringio"
+require_relative "adapter"
+require_relative "task_mapper"
+
+module A2A
+  module Rails
+    module Protocol
+      class Agent2AgentAdapter < Adapter
+        PROTOCOL_VERSION = "1.0"
+        SUPPORTED_OPERATIONS = %w[SendMessage GetTask ListTasks CancelTask].freeze
+        RESPONSE_SCHEMAS = {
+          "SendMessage" => "Send Message Response",
+          "GetTask" => "Task",
+          "ListTasks" => "List Tasks Response",
+          "CancelTask" => "Task"
+        }.freeze
+
+        def initialize(agent_card:, request_handler:, sdk_factory: nil)
+          unless request_handler.respond_to?(:call)
+            raise ArgumentError, "request_handler must respond to #call"
+          end
+
+          @request_handler = request_handler
+          factory = sdk_factory || A2A.method(:agent)
+          @sdk = factory.call(agent_card: agent_card) { |env| dispatch(env) }
+        end
+
+        def call(env)
+          status, headers, body = with_sensitive_sdk_logging_suppressed do
+            @sdk.call(normalize_env(env))
+          end
+          [status, headers.merge("a2a-version" => PROTOCOL_VERSION), body]
+        end
+
+        private
+
+        def with_sensitive_sdk_logging_suppressed
+          return yield unless defined?(::Console) && ::Console.respond_to?(:logger)
+          return yield unless defined?(::Console::Logger::WARN) && defined?(::A2A::Server::Triage)
+
+          logger = ::Console.logger
+          return yield unless logger.respond_to?(:subjects)
+
+          subjects = logger.subjects
+          triage = ::A2A::Server::Triage
+          had_override = subjects.key?(triage)
+          previous_level = subjects[triage]
+          subjects[triage] = ::Console::Logger::WARN
+
+          yield
+        ensure
+          if defined?(subjects) && subjects
+            if had_override
+              subjects[triage] = previous_level
+            else
+              subjects.delete(triage)
+            end
+          end
+        end
+
+        def normalize_env(env)
+          input = env.fetch("rack.input")
+          env.merge(
+            "PATH_INFO" => "/",
+            "rack.input" => StringIO.new(input.read.to_s)
+          )
+        end
+
+        def dispatch(env)
+          validate_version!(env)
+
+          operation = env.fetch("a2a.operation")
+          raise A2A::UnsupportedOperationError.new unless SUPPORTED_OPERATIONS.include?(operation)
+
+          request = env.fetch("a2a.request")
+          validate_request!(request)
+
+          result = @request_handler.call(operation: operation, params: request.to_h)
+          schema(RESPONSE_SCHEMAS.fetch(operation), result)
+        rescue A2A::Rails::TaskNotFoundError => error
+          raise A2A::TaskNotFoundError.new(error.task_id)
+        rescue A2A::Rails::TaskNotCancelableError => error
+          raise A2A::TaskNotCancelableError.new(
+            error.task_id,
+            state: TaskMapper.wire_state(error.state)
+          )
+        rescue A2A::Rails::InvalidRequestError,
+          A2A::Rails::InvalidTaskQueryError,
+          A2A::Rails::InvalidTaskStateError => error
+          raise A2A::InvalidParamsError.new(error.message)
+        rescue A2A::Rails::ContentTypeNotSupportedError
+          raise A2A::ContentTypeNotSupportedError.new
+        rescue A2A::Rails::TaskContinuationNotSupportedError => error
+          raise A2A::UnsupportedOperationError.new(message: error.message)
+        end
+
+        def validate_version!(env)
+          version = env["HTTP_A2A_VERSION"]
+          if version.nil? || version.empty?
+            version = Rack::Utils.parse_query(env["QUERY_STRING"].to_s)["A2A-Version"]
+          end
+          version = "0.3" if version.nil? || version.empty?
+
+          raise A2A::VersionNotSupportedError.new(version) unless version == PROTOCOL_VERSION
+        end
+
+        def validate_request!(request)
+          request.valid!
+        rescue A2A::Protocol::JsonSchema::ValidationError
+          raise A2A::InvalidParamsError.new("Invalid request parameters")
+        end
+
+        def schema(name, value)
+          object = A2A::Protocol::JsonSchema[name].new(value)
+          object.valid!
+          object
+        end
+      end
+    end
+  end
+end