a2a-rails 0.1.0

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+require "time"
+require_relative "store"
+
+module A2A
+  module Rails
+    module Task
+      class MemoryStore < Store
+        UNSET = Object.new.freeze
+        DEFAULT_PAGE_SIZE = 50
+        MAX_PAGE_SIZE = 100
+
+        def initialize
+          @tasks = {}
+          @pages = {}
+          @mutex = Mutex.new
+        end
+
+        def save(task)
+          id = task.fetch(:id)
+          @mutex.synchronize do
+            @tasks[id] = copy(task)
+            copy(@tasks[id])
+          end
+        end
+
+        def find(task_id)
+          @mutex.synchronize { copy(find!(task_id)) }
+        end
+
+        def transition(task_id, state:, timestamp: Time.now.utc, artifacts: UNSET, message: UNSET)
+          validate_state!(state)
+
+          @mutex.synchronize do
+            task = find!(task_id)
+            return copy(task) if terminal?(task)
+
+            task[:status] = status_hash(state, timestamp, message)
+            task[:artifacts] = copy(artifacts) unless artifacts.equal?(UNSET)
+            copy(task)
+          end
+        end
+
+        def cancel(task_id, timestamp: Time.now.utc)
+          @mutex.synchronize do
+            task = find!(task_id)
+            state = task.dig(:status, :state)
+            raise TaskNotCancelableError.new(task_id, state: state) if TERMINAL_STATES.include?(state)
+
+            task[:status] = status_hash(:canceled, timestamp, UNSET)
+            copy(task)
+          end
+        end
+
+        def list(context_id: nil, status: nil, status_timestamp_after: nil,
+          page_size: DEFAULT_PAGE_SIZE, page_token: nil)
+          validate_page_size!(page_size)
+          validate_state!(status) if status
+          after = normalize_time(status_timestamp_after) if status_timestamp_after
+          fingerprint = query_fingerprint(context_id:, status:, status_timestamp_after: after, page_size:)
+
+          @mutex.synchronize do
+            rows, offset = page_rows(page_token, fingerprint) do
+              filtered_rows(context_id:, status:, status_timestamp_after: after)
+            end
+
+            next_offset = offset + page_size
+            next_token = ""
+            if next_offset < rows.length
+              next_token = SecureRandom.uuid
+              @pages[next_token] = { rows: rows, offset: next_offset, fingerprint: fingerprint }
+            end
+
+            {
+              tasks: copy(rows.slice(offset, page_size) || []),
+              total_size: rows.length,
+              page_size: page_size,
+              next_page_token: next_token
+            }
+          end
+        end
+
+        private
+
+        def find!(task_id)
+          @tasks[task_id] || raise(TaskNotFoundError, task_id)
+        end
+
+        def terminal?(task)
+          TERMINAL_STATES.include?(task.dig(:status, :state))
+        end
+
+        def validate_state!(state)
+          return if STATES.include?(state)
+
+          raise InvalidTaskStateError, "Unknown task state: #{state.inspect}"
+        end
+
+        def validate_page_size!(page_size)
+          return if page_size.is_a?(Integer) && (1..MAX_PAGE_SIZE).cover?(page_size)
+
+          raise InvalidTaskQueryError, "page_size must be an integer from 1 to #{MAX_PAGE_SIZE}"
+        end
+
+        def normalize_time(value)
+          return value.utc if value.respond_to?(:utc) && !value.is_a?(String)
+
+          Time.iso8601(value.to_s).utc
+        rescue ArgumentError
+          raise InvalidTaskQueryError, "status_timestamp_after must be an ISO 8601 timestamp"
+        end
+
+        def status_hash(state, timestamp, message)
+          status = { state: state, timestamp: normalize_time(timestamp).iso8601(6) }
+          status[:message] = message unless message.equal?(UNSET)
+          status
+        end
+
+        def page_rows(page_token, fingerprint)
+          if page_token && !page_token.empty?
+            cursor = @pages[page_token]
+            unless cursor && cursor[:fingerprint] == fingerprint
+              raise InvalidTaskQueryError, "Invalid page_token or changed query"
+            end
+
+            [cursor[:rows], cursor[:offset]]
+          else
+            [copy(yield), 0]
+          end
+        end
+
+        def filtered_rows(context_id:, status:, status_timestamp_after:)
+          @tasks.values
+            .select do |task|
+              (!context_id || task[:context_id] == context_id) &&
+                (!status || task.dig(:status, :state) == status) &&
+                (!status_timestamp_after || task_time(task) >= status_timestamp_after)
+            end
+            .sort_by { |task| [task_time(task), task.fetch(:id)] }
+            .reverse
+        end
+
+        def task_time(task)
+          Time.iso8601(task.dig(:status, :timestamp))
+        end
+
+        def query_fingerprint(context_id:, status:, status_timestamp_after:, page_size:)
+          normalized = [context_id, status, status_timestamp_after&.iso8601(6), page_size]
+          Digest::SHA256.hexdigest(Marshal.dump(normalized))
+        end
+
+        def copy(value)
+          Marshal.load(Marshal.dump(value))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module Task
+      class ResultMapper
+        FAILURE_MESSAGE = "Task execution failed"
+        REJECTION_MESSAGE = "Task rejected"
+
+        def initialize(artifact_mapper: ArtifactMapper.new)
+          @artifact_mapper = artifact_mapper
+        end
+
+        def completed(value)
+          artifact = @artifact_mapper.call(value)
+          outcome = { state: :completed }
+          outcome[:artifacts] = [artifact] if artifact
+          outcome
+        end
+
+        def rejected(error)
+          message = error.message.to_s.empty? ? REJECTION_MESSAGE : error.message.to_s
+          { state: :rejected, message: message }
+        end
+
+        def failed(_error)
+          { state: :failed, message: FAILURE_MESSAGE }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module Task
+      class Store
+        def save(_task)
+          raise NotImplementedError, "Task stores must implement #save"
+        end
+
+        def find(_task_id)
+          raise NotImplementedError, "Task stores must implement #find"
+        end
+
+        def transition(_task_id, state:, **_attributes)
+          raise NotImplementedError, "Task stores must implement #transition"
+        end
+
+        def cancel(_task_id, **_attributes)
+          raise NotImplementedError, "Task stores must implement #cancel"
+        end
+
+        def list(**_filters)
+          raise NotImplementedError, "Task stores must implement #list"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/rails/task.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    module Task
+      STATES = %i[submitted working completed failed rejected canceled].freeze
+      TERMINAL_STATES = %i[completed failed rejected canceled].freeze
+    end
+  end
+end
+
+require_relative "task/store"
+require_relative "task/memory_store"
+require_relative "task/artifact_mapper"
+require_relative "task/result_mapper"
+require_relative "task/lifecycle"

data/lib/a2a/rails/version.rb

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

data/lib/a2a-rails.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "a2a/rails/version"
+require_relative "a2a/rails/errors"
+require_relative "a2a/rails/configuration"
+require_relative "a2a/rails/skill"
+require_relative "a2a/rails/agent"
+require_relative "a2a/rails/dispatcher"
+require_relative "a2a/rails/agent_card/validator"
+require_relative "a2a/rails/agent_card/builder"
+require_relative "a2a/rails/task"
+require_relative "a2a/rails/protocol/adapter"
+require_relative "a2a/rails/protocol/task_mapper"
+require_relative "a2a/rails/protocol/request_handler"
+require_relative "a2a/rails/protocol/agent2agent_adapter"
+require_relative "a2a/rails/runtime"
+require_relative "a2a/rails/engine"
+
+module A2A
+  module Rails
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+        configuration
+      end
+
+      def runtime
+        @runtime ||= Runtime.new
+      end
+    end
+  end
+end

data/lib/generators/a2a/rails/agent_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module A2A
+  module Rails
+    class AgentGenerator < ::Rails::Generators::NamedBase
+      namespace "a2a:rails:agent"
+      source_root File.expand_path("templates", __dir__)
+
+      def create_agent
+        template "agent.rb.tt", File.join("app/agents", class_path, "#{file_name}_agent.rb")
+      end
+
+      def agent_display_name
+        file_name.split("_").map(&:capitalize).join(" ")
+      end
+    end
+  end
+end

data/lib/generators/a2a/rails/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module A2A
+  module Rails
+    class InstallGenerator < ::Rails::Generators::Base
+      namespace "a2a:rails:install"
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/a2a_rails.rb"
+      end
+    end
+  end
+end

data/lib/generators/a2a/rails/templates/agent.rb.tt

@@ -0,0 +1,7 @@
+class <%= class_name %>Agent < A2A::Rails::Agent
+  name "<%= agent_display_name %> Agent"
+  description "TODO"
+  version "1.0"
+
+  # Add at least one skill.
+end

data/lib/generators/a2a/rails/templates/initializer.rb.tt

@@ -0,0 +1,4 @@
+A2A::Rails.configure do |config|
+  config.agent = "YourAgent"
+  config.public_base_url = ENV["A2A_PUBLIC_BASE_URL"]
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: a2a-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- cuichangquan
+bindir: bin
+cert_chain: []
+date: 2026-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: agent2agent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: Expose Rails applications as A2A agents while keeping protocol SDK details
+  behind an internal adapter boundary.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/a2a/rails/agent_cards_controller.rb
+- app/controllers/a2a/rails/application_controller.rb
+- app/controllers/a2a/rails/requests_controller.rb
+- config/routes.rb
+- lib/a2a-rails.rb
+- lib/a2a/rails/agent.rb
+- lib/a2a/rails/agent_card/builder.rb
+- lib/a2a/rails/agent_card/validator.rb
+- lib/a2a/rails/configuration.rb
+- lib/a2a/rails/dispatcher.rb
+- lib/a2a/rails/engine.rb
+- lib/a2a/rails/errors.rb
+- lib/a2a/rails/protocol/adapter.rb
+- lib/a2a/rails/protocol/agent2agent_adapter.rb
+- lib/a2a/rails/protocol/request_handler.rb
+- lib/a2a/rails/protocol/task_mapper.rb
+- lib/a2a/rails/runtime.rb
+- lib/a2a/rails/skill.rb
+- lib/a2a/rails/task.rb
+- lib/a2a/rails/task/artifact_mapper.rb
+- lib/a2a/rails/task/lifecycle.rb
+- lib/a2a/rails/task/memory_store.rb
+- lib/a2a/rails/task/result_mapper.rb
+- lib/a2a/rails/task/store.rb
+- lib/a2a/rails/version.rb
+- lib/generators/a2a/rails/agent_generator.rb
+- lib/generators/a2a/rails/install_generator.rb
+- lib/generators/a2a/rails/templates/agent.rb.tt
+- lib/generators/a2a/rails/templates/initializer.rb.tt
+homepage: https://github.com/cuichangquan/a2a-rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cuichangquan/a2a-rails
+  changelog_uri: https://github.com/cuichangquan/a2a-rails/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/cuichangquan/a2a-rails#readme
+  bug_tracker_uri: https://github.com/cuichangquan/a2a-rails/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.4
+specification_version: 4
+summary: Rails-native integration for exposing Rails applications as A2A agents
+test_files: []