a2a-rails 0.1.0

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

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module Protocol
+      class RequestHandler
+        def initialize(dispatcher:, lifecycle:, task_mapper: TaskMapper.new)
+          @dispatcher = dispatcher
+          @lifecycle = lifecycle
+          @task_mapper = task_mapper
+        end
+
+        def call(operation:, params:)
+          validate_common!(params)
+
+          case operation
+          when "SendMessage"
+            send_message(params)
+          when "GetTask"
+            get_task(params)
+          when "ListTasks"
+            list_tasks(params)
+          when "CancelTask"
+            cancel_task(params)
+          else
+            raise InvalidRequestError, "Unsupported operation: #{operation}"
+          end
+        end
+
+        private
+
+        def send_message(params)
+          @dispatcher.validate!
+          history_length = history_length(params)
+          message, context_id = normalize_message(params)
+
+          task = @lifecycle.create(message: message, context_id: context_id)
+          @lifecycle.start(task.fetch(:id))
+          context = { task_id: task.fetch(:id), context_id: task.fetch(:context_id) }
+
+          task = begin
+            result = @dispatcher.call(message: message, context: context)
+            @lifecycle.complete(task.fetch(:id), result)
+          rescue RejectedTask => error
+            @lifecycle.reject(task.fetch(:id), error)
+          rescue StandardError => error
+            @lifecycle.fail(task.fetch(:id), error)
+          end
+
+          { "task" => @task_mapper.dump(task, history_length: history_length, include_artifacts: true) }
+        end
+
+        def get_task(params)
+          history_length = history_length(params)
+          task = @lifecycle.find(required_id(params))
+          @task_mapper.dump(task, history_length: history_length, include_artifacts: true)
+        end
+
+        def list_tasks(params)
+          history_length = history_length(params)
+          filters = {}
+          filters[:context_id] = params["contextId"] if params.key?("contextId")
+          filters[:status] = @task_mapper.internal_state(params["status"]) if params.key?("status")
+          filters[:status_timestamp_after] = params["statusTimestampAfter"] if params.key?("statusTimestampAfter")
+          filters[:page_size] = params["pageSize"] if params.key?("pageSize")
+          filters[:page_token] = params["pageToken"] if params.key?("pageToken")
+
+          result = @lifecycle.list(**filters)
+          include_artifacts = params["includeArtifacts"] == true
+
+          {
+            "tasks" => result.fetch(:tasks).map do |task|
+              @task_mapper.dump(task, history_length: history_length, include_artifacts: include_artifacts)
+            end,
+            "totalSize" => result.fetch(:total_size),
+            "pageSize" => result.fetch(:page_size),
+            "nextPageToken" => result.fetch(:next_page_token)
+          }
+        end
+
+        def cancel_task(params)
+          task = @lifecycle.cancel(required_id(params))
+          @task_mapper.dump(task, include_artifacts: true)
+        end
+
+        def normalize_message(params)
+          raw = params["message"]
+          unless raw.is_a?(Hash)
+            raise InvalidRequestError, "message is required"
+          end
+
+          message_id = raw["messageId"]
+          unless message_id.is_a?(String) && !message_id.empty?
+            raise InvalidRequestError, "messageId is required"
+          end
+
+          unless raw["role"] == "ROLE_USER"
+            raise InvalidRequestError, "ROLE_USER is required"
+          end
+
+          parts = raw["parts"]
+          unless parts.is_a?(Array) && !parts.empty?
+            raise InvalidRequestError, "nonempty parts are required"
+          end
+
+          if raw["taskId"].is_a?(String) && !raw["taskId"].empty?
+            @lifecycle.find(raw["taskId"])
+            raise TaskContinuationNotSupportedError, "Task continuation is not supported in v0.1"
+          end
+
+          normalized_parts = parts.map { |part| normalize_text_part(part) }
+          message = {
+            message_id: message_id,
+            role: :user,
+            parts: normalized_parts,
+            metadata: copy(raw["metadata"] || {})
+          }
+
+          [message, raw["contextId"]]
+        end
+
+        def normalize_text_part(part)
+          unless part.is_a?(Hash) && part["text"].is_a?(String) && (part.keys & %w[data raw url]).empty?
+            raise ContentTypeNotSupportedError, "Only text Parts are supported in v0.1"
+          end
+
+          normalized = {
+            text: part["text"],
+            media_type: part["mediaType"].to_s.empty? ? "text/plain" : part["mediaType"]
+          }
+          normalized[:metadata] = copy(part["metadata"]) if part.key?("metadata")
+          normalized
+        end
+
+        def required_id(params)
+          id = params["id"]
+          unless id.is_a?(String) && !id.empty?
+            raise InvalidRequestError, "id is required"
+          end
+
+          id
+        end
+
+        def history_length(params)
+          return nil unless params.key?("historyLength")
+
+          value = params["historyLength"]
+          unless value.is_a?(Integer) && value >= 0
+            raise InvalidRequestError, "historyLength must be a nonnegative integer"
+          end
+
+          value
+        end
+
+        def validate_common!(params)
+          unless params.is_a?(Hash)
+            raise InvalidRequestError, "params must be an object"
+          end
+
+          tenant = params["tenant"]
+          if tenant && !tenant.to_s.empty?
+            raise InvalidRequestError, "tenant is not supported in v0.1"
+          end
+        end
+
+        def copy(value)
+          Marshal.load(Marshal.dump(value))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module Protocol
+      class TaskMapper
+        STATE_TO_WIRE = {
+          submitted: "TASK_STATE_SUBMITTED",
+          working: "TASK_STATE_WORKING",
+          completed: "TASK_STATE_COMPLETED",
+          failed: "TASK_STATE_FAILED",
+          rejected: "TASK_STATE_REJECTED",
+          canceled: "TASK_STATE_CANCELED"
+        }.freeze
+        WIRE_TO_STATE = STATE_TO_WIRE.invert.freeze
+
+        def dump(task, history_length: nil, include_artifacts: true)
+          result = {
+            "id" => task.fetch(:id),
+            "contextId" => task.fetch(:context_id),
+            "status" => dump_status(task)
+          }
+
+          if task.key?(:history)
+            history = project_history(task[:history], history_length)
+            result["history"] = history.map { |message| dump_message(message) }
+          end
+
+          if include_artifacts && task.key?(:artifacts)
+            result["artifacts"] = task[:artifacts].map { |artifact| dump_artifact(artifact) }
+          end
+
+          result
+        end
+
+        def internal_state(value)
+          return nil if value.nil?
+
+          WIRE_TO_STATE.fetch(value) do
+            raise InvalidTaskStateError, "Unknown task state: #{value.inspect}"
+          end
+        end
+
+        def self.wire_state(value)
+          STATE_TO_WIRE.fetch(value) { value.to_s }
+        end
+
+        private
+
+        def dump_status(task)
+          status = task.fetch(:status)
+          result = {
+            "state" => self.class.wire_state(status.fetch(:state)),
+            "timestamp" => status[:timestamp]
+          }
+
+          if status[:message]
+            result["message"] = {
+              "messageId" => "status-#{task.fetch(:id)}-#{status.fetch(:state)}",
+              "role" => "ROLE_AGENT",
+              "parts" => [{ "text" => status[:message].to_s }]
+            }
+          end
+
+          result.compact
+        end
+
+        def dump_message(message)
+          result = {
+            "messageId" => message.fetch(:message_id),
+            "role" => message.fetch(:role) == :agent ? "ROLE_AGENT" : "ROLE_USER",
+            "parts" => message.fetch(:parts).map { |part| dump_part(part) }
+          }
+          result["metadata"] = copy(message[:metadata]) if message.key?(:metadata)
+          result
+        end
+
+        def dump_artifact(artifact)
+          {
+            "artifactId" => artifact.fetch(:artifact_id),
+            "parts" => artifact.fetch(:parts).map { |part| dump_part(part) }
+          }
+        end
+
+        def dump_part(part)
+          result = {}
+          result["text"] = part[:text] if part.key?(:text)
+          result["data"] = copy(part[:data]) if part.key?(:data)
+          result["metadata"] = copy(part[:metadata]) if part.key?(:metadata)
+          result
+        end
+
+        def project_history(history, history_length)
+          return history if history_length.nil?
+          return [] if history_length.zero?
+
+          history.last(history_length)
+        end
+
+        def copy(value)
+          Marshal.load(Marshal.dump(value))
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/runtime.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Runtime
+      def initialize(store: Task::MemoryStore.new)
+        @store = store
+      end
+
+      def agent_card(request_base_url:)
+        configuration = A2A::Rails.configuration
+        agent = configuration.resolve_agent
+
+        AgentCard::Builder.new(
+          agent: agent,
+          public_base_url: configuration.normalized_public_base_url,
+          request_base_url: request_base_url
+        ).call
+      end
+
+      def call(env:, request_base_url:)
+        configuration = A2A::Rails.configuration
+        agent = configuration.resolve_agent
+        card = AgentCard::Builder.new(
+          agent: agent,
+          public_base_url: configuration.normalized_public_base_url,
+          request_base_url: request_base_url
+        ).call
+        lifecycle = Task::Lifecycle.new(store: @store, logger: configuration.logger)
+        request_handler = Protocol::RequestHandler.new(
+          dispatcher: Dispatcher.new(agent: agent),
+          lifecycle: lifecycle
+        )
+        adapter = Protocol::Agent2AgentAdapter.new(
+          agent_card: card,
+          request_handler: request_handler
+        )
+
+        adapter.call(env)
+      end
+    end
+  end
+end

data/lib/a2a/rails/skill.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class Skill
+      attr_reader :id, :name, :description, :tags, :handler, :examples, :input_modes, :output_modes
+
+      def initialize(id:, description:, tags:, handler:, name: nil, examples: nil, input_modes: nil, output_modes: nil)
+        @id = normalize_id(id)
+        @name = normalize_text(name || humanize_id(@id))
+        @description = normalize_optional_text(description)
+        @tags = Array(tags).map { |tag| normalize_text(tag) }.freeze
+        @handler = handler
+        @examples = normalize_optional_collection(examples)
+        @input_modes = normalize_optional_collection(input_modes)
+        @output_modes = normalize_optional_collection(output_modes)
+        freeze
+      end
+
+      def validate!
+        if @id.to_s.empty?
+          raise ConfigurationError, "Skill id must not be empty"
+        end
+
+        if @description.nil? || @description.strip.empty?
+          raise ConfigurationError, "Skill #{@id.inspect} must define a description"
+        end
+
+        if @tags.empty? || @tags.any? { |tag| tag.strip.empty? }
+          raise ConfigurationError, "Skill #{@id.inspect} must define at least one non-empty tag"
+        end
+
+        validate_optional_strings!(:examples, @examples, allow_empty: true)
+        validate_optional_strings!(:input_modes, @input_modes, allow_empty: false)
+        validate_optional_strings!(:output_modes, @output_modes, allow_empty: false)
+
+        unless @handler.respond_to?(:call)
+          raise InvalidHandlerError, "Handler #{handler_label} must respond to .call"
+        end
+
+        self
+      end
+
+      private
+
+      def normalize_id(value)
+        value.to_sym
+      rescue NoMethodError
+        raise ConfigurationError, "Skill id must be convertible to a Symbol"
+      end
+
+      def normalize_text(value)
+        value.to_s.dup.freeze
+      end
+
+      def normalize_optional_text(value)
+        return if value.nil?
+
+        normalize_text(value)
+      end
+
+      def normalize_optional_collection(value)
+        return if value.nil?
+        return value unless value.is_a?(Array)
+
+        value.map { |entry| entry.is_a?(String) ? entry.dup.freeze : entry }.freeze
+      end
+
+      def validate_optional_strings!(field, value, allow_empty:)
+        return if value.nil?
+
+        valid = value.is_a?(Array) &&
+          (allow_empty || !value.empty?) &&
+          value.all? { |entry| entry.is_a?(String) && !entry.strip.empty? }
+        return if valid
+
+        requirement = allow_empty ? "an Array of non-empty Strings" : "a non-empty Array of non-empty Strings"
+        raise ConfigurationError, "Skill #{@id.inspect} #{field} must be #{requirement}"
+      end
+
+      def humanize_id(value)
+        value.to_s.split("_").map!(&:capitalize).join(" ")
+      end
+
+      def handler_label
+        return @handler.name if @handler.respond_to?(:name) && @handler.name
+
+        @handler.inspect
+      end
+    end
+  end
+end

data/lib/a2a/rails/task/artifact_mapper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module A2A
+  module Rails
+    module Task
+      class ArtifactMapper
+        def initialize(id_generator: -> { SecureRandom.uuid })
+          @id_generator = id_generator
+        end
+
+        def call(value)
+          case value
+          when nil
+            nil
+          when String
+            artifact(parts: [{ text: value }])
+          when Hash, Array
+            artifact(parts: [{ data: copy(value) }])
+          else
+            raise ArtifactMappingError, "Unsupported Handler result type: #{value.class}"
+          end
+        end
+
+        private
+
+        def artifact(parts:)
+          { artifact_id: @id_generator.call.to_s, parts: parts }
+        end
+
+        def copy(value)
+          Marshal.load(Marshal.dump(value))
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/task/lifecycle.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module A2A
+  module Rails
+    module Task
+      class Lifecycle
+        def initialize(store:, result_mapper: ResultMapper.new, logger: nil,
+          clock: -> { Time.now.utc }, id_generator: -> { SecureRandom.uuid })
+          @store = store
+          @result_mapper = result_mapper
+          @logger = logger
+          @clock = clock
+          @id_generator = id_generator
+        end
+
+        def create(message:, context_id: nil)
+          task = {
+            id: next_id,
+            context_id: present_context_id(context_id),
+            status: status(:submitted),
+            history: [copy(message)]
+          }
+
+          @store.save(task)
+        end
+
+        def start(task_id)
+          @store.transition(task_id, state: :working, timestamp: now)
+        end
+
+        def complete(task_id, result)
+          transition_from_outcome(task_id, @result_mapper.completed(result))
+        end
+
+        def reject(task_id, error)
+          transition_from_outcome(task_id, @result_mapper.rejected(error))
+        end
+
+        def fail(task_id, error)
+          log_failure(task_id, error)
+          transition_from_outcome(task_id, @result_mapper.failed(error))
+        end
+
+        def cancel(task_id)
+          @store.cancel(task_id, timestamp: now)
+        end
+
+        def find(task_id)
+          @store.find(task_id)
+        end
+
+        def list(**filters)
+          @store.list(**filters)
+        end
+
+        private
+
+        def transition_from_outcome(task_id, outcome)
+          attributes = { state: outcome.fetch(:state), timestamp: now }
+          attributes[:artifacts] = outcome[:artifacts] if outcome.key?(:artifacts)
+          attributes[:message] = outcome[:message] if outcome.key?(:message)
+          @store.transition(task_id, **attributes)
+        end
+
+        def status(state)
+          { state: state, timestamp: now.iso8601(6) }
+        end
+
+        def present_context_id(context_id)
+          return context_id unless context_id.nil? || context_id.to_s.empty?
+
+          next_id
+        end
+
+        def next_id
+          @id_generator.call.to_s
+        end
+
+        def now
+          @clock.call.utc
+        end
+
+        def log_failure(task_id, error)
+          return unless @logger
+
+          @logger.error("[a2a-rails] task_id=#{task_id} execution failed: #{error.class}: #{error.message}")
+          @logger.error(error.backtrace.join("\n")) if error.backtrace && !error.backtrace.empty?
+        end
+
+        def copy(value)
+          Marshal.load(Marshal.dump(value))
+        end
+      end
+    end
+  end
+end