a2a-rails 0.1.0 → 0.2.0

data/lib/a2a/rails/task_execution_arguments.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class TaskExecutionArguments
+      MAX_IDENTIFIER_BYTES = 256
+      MAX_CLASS_NAME_BYTES = 512
+      KEYS = %i[task_id principal_id agent_class_name skill_id].freeze
+
+      attr_reader(*KEYS)
+
+      def initialize(task_id:, principal_id:, agent_class_name:, skill_id:)
+        @task_id = normalize_identifier(task_id, "task_id")
+        @principal_id = normalize_principal_id(principal_id)
+        @agent_class_name = normalize_agent_class_name(agent_class_name)
+        @skill_id = normalize_skill_id(skill_id)
+        @payload = {
+          task_id: @task_id,
+          principal_id: @principal_id,
+          agent_class_name: @agent_class_name,
+          skill_id: @skill_id
+        }.freeze
+        freeze
+      end
+
+      def to_h
+        @payload
+      end
+
+      private
+
+      def normalize_identifier(value, label)
+        unless safe_string?(value, max_bytes: MAX_IDENTIFIER_BYTES)
+          raise ConfigurationError, "#{label} must be a non-empty safe String"
+        end
+
+        value.dup.freeze
+      end
+
+      def normalize_principal_id(value)
+        return nil if value.nil?
+
+        unless Authentication.valid_principal_id?(value)
+          raise ConfigurationError, "principal_id must be a valid non-secret principal ID String"
+        end
+
+        value.dup.freeze
+      end
+
+      def normalize_agent_class_name(value)
+        return nil if value.nil?
+
+        unless safe_string?(value, max_bytes: MAX_CLASS_NAME_BYTES)
+          raise ConfigurationError, "agent_class_name must be a safe class-name String"
+        end
+
+        parts = value.sub(/\A::/, "").split("::")
+        unless parts.all? { |part| part.match?(/\A[A-Z]\w*\z/) }
+          raise ConfigurationError, "agent_class_name must be a valid class-name String"
+        end
+
+        value.dup.freeze
+      end
+
+      def normalize_skill_id(value)
+        string = value.is_a?(Symbol) ? value.to_s : value
+        normalize_identifier(string, "skill_id")
+      end
+
+      def safe_string?(value, max_bytes:)
+        value.is_a?(String) &&
+          !value.strip.empty? &&
+          value.bytesize <= max_bytes &&
+          !value.match?(/[[:cntrl:]]/)
+      end
+    end
+  end
+end

data/lib/a2a/rails/task_execution_job.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module A2A
+  module Rails
+    class TaskExecutionJob < ::ActiveJob::Base
+      queue_as :default
+      # The Task is already persisted before enqueue. Keep the enqueue boundary
+      # immediate and independent from any surrounding host Active Record transaction.
+      self.enqueue_after_transaction_commit = false
+
+      def perform(task_id:, principal_id:, agent_class_name:, skill_id:)
+        arguments = TaskExecutionArguments.new(
+          task_id: task_id,
+          principal_id: principal_id,
+          agent_class_name: agent_class_name,
+          skill_id: skill_id
+        )
+        task_id = arguments.task_id
+        principal_id = arguments.principal_id
+        agent_class_name = arguments.agent_class_name
+        skill_id = arguments.skill_id
+
+        configuration = A2A::Rails.configuration
+        lifecycle = Task::Lifecycle.new(
+          store: A2A::Rails.runtime.task_store,
+          logger: configuration.logger,
+          principal_id: principal_id
+        )
+
+        claimed = lifecycle.claim_execution(task_id)
+        return unless claimed
+
+        agent = configuration.resolve_agent
+        unless agent_class_name.nil? || agent.name == agent_class_name
+          raise ConfigurationError, "Queued Agent no longer matches configured Agent"
+        end
+
+        message = original_message(claimed)
+        plan = ExecutionPlan.new(
+          agent_class_name: agent_class_name,
+          skill_id: skill_id,
+          execution_mode: :async
+        )
+        context = {
+          task_id: task_id,
+          context_id: claimed.fetch(:context_id),
+          principal_id: principal_id,
+          idempotency_key: task_id
+        }
+
+        result = Dispatcher.new(agent: agent, configuration: configuration).execute(
+          plan: plan,
+          message: message,
+          context: context
+        )
+        lifecycle.complete(task_id, result)
+      rescue RejectedTask => error
+        lifecycle&.reject(task_id, error)
+      rescue TaskNotFoundError
+        nil
+      rescue StandardError => error
+        lifecycle&.fail(task_id, error) if lifecycle
+      end
+
+      private
+
+      def original_message(task)
+        history = task[:history]
+        unless history.is_a?(Array) && history.first.is_a?(Hash)
+          raise ConfigurationError, "Queued Task does not contain an original Message"
+        end
+
+        history.first
+      end
+    end
+  end
+end

data/lib/a2a/rails/version.rb

@@ -2,6 +2,6 @@
 
 module A2A
   module Rails
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/a2a-rails.rb

@@ -2,13 +2,20 @@
 
 require_relative "a2a/rails/version"
 require_relative "a2a/rails/errors"
+require_relative "a2a/rails/file_artifact"
+require_relative "a2a/rails/authentication"
+require_relative "a2a/rails/request_guard"
 require_relative "a2a/rails/configuration"
 require_relative "a2a/rails/skill"
 require_relative "a2a/rails/agent"
+require_relative "a2a/rails/execution_plan"
 require_relative "a2a/rails/dispatcher"
+require_relative "a2a/rails/agent_card/security"
 require_relative "a2a/rails/agent_card/validator"
 require_relative "a2a/rails/agent_card/builder"
 require_relative "a2a/rails/task"
+require_relative "a2a/rails/task_execution_arguments"
+require_relative "a2a/rails/task_execution_job"
 require_relative "a2a/rails/protocol/adapter"
 require_relative "a2a/rails/protocol/task_mapper"
 require_relative "a2a/rails/protocol/request_handler"

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+begin
+  require "rails/generators"
+  require "rails/generators/migration"
+  require "active_record"
+  require "rails/generators/active_record"
+rescue LoadError => error
+  raise LoadError,
+    "a2a:rails:task_store requires ActiveRecord in the host application (#{error.path})"
+end
+
+module A2A
+  module Rails
+    class TaskStoreGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      namespace "a2a:rails:task_store"
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_task_store_migration
+        migration_template(
+          "create_a2a_rails_tasks.rb.tt",
+          "db/migrate/create_a2a_rails_tasks.rb"
+        )
+      end
+
+      def show_configuration
+        say <<~MESSAGE
+
+          Configure the durable store in config/initializers/a2a_rails.rb:
+
+            config.task_store = :active_record
+
+          Then run:
+
+            bin/rails db:migrate
+        MESSAGE
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+class <%= ::ActiveSupport::Inflector.camelize("create_a2a_rails_tasks") %> < ActiveRecord::Migration[8.0]
+  def change
+    create_table :a2a_rails_tasks do |t|
+      t.string :task_id, null: false
+      t.string :owner_id
+      t.string :context_id, null: false
+      t.string :state, null: false
+      t.datetime :status_timestamp, precision: 6, null: false
+      t.json :status_message
+      t.json :history
+      t.json :artifacts
+      t.datetime :expires_at, precision: 6
+
+      t.timestamps
+    end
+
+    add_index :a2a_rails_tasks, :task_id,
+      unique: true,
+      name: "idx_a2a_tasks_task_id"
+    add_index :a2a_rails_tasks, [:owner_id, :task_id],
+      name: "idx_a2a_tasks_owner_task"
+    add_index :a2a_rails_tasks, [:owner_id, :context_id, :status_timestamp],
+      name: "idx_a2a_tasks_owner_context_time"
+    add_index :a2a_rails_tasks, [:owner_id, :state, :status_timestamp],
+      name: "idx_a2a_tasks_owner_state_time"
+    add_index :a2a_rails_tasks, [:owner_id, :status_timestamp],
+      name: "idx_a2a_tasks_owner_time"
+    add_index :a2a_rails_tasks, :expires_at,
+      name: "idx_a2a_tasks_expires_at"
+  end
+end

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

@@ -1,4 +1,8 @@
 A2A::Rails.configure do |config|
   config.agent = "YourAgent"
   config.public_base_url = ENV["A2A_PUBLIC_BASE_URL"]
+
+  # Production/staging A2A requests fail closed unless the host configures
+  # config.authenticate_request and matching Agent Card security metadata.
+  # See: https://github.com/cuichangquan/a2a-rails/blob/main/docs/guides/authentication.md
 end

data/lib/tasks/a2a_rails_tasks.rake

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+namespace :a2a do
+  namespace :rails do
+    namespace :tasks do
+      desc "Delete expired a2a-rails Tasks in bounded batches"
+      task prune: :environment do
+        store = A2A::Rails.configuration.resolve_task_store
+        unless store.respond_to?(:prune_expired)
+          abort "Configured a2a-rails Task Store does not support pruning"
+        end
+
+        max_batches = Integer(ENV.fetch("A2A_TASK_PRUNE_MAX_BATCHES", "100"), 10)
+        abort "A2A_TASK_PRUNE_MAX_BATCHES must be positive" unless max_batches.positive?
+
+        total = 0
+        batches = 0
+
+        while batches < max_batches
+          deleted = store.prune_expired
+          break if deleted.zero?
+
+          total += deleted
+          batches += 1
+        end
+
+        stats = store.respond_to?(:maintenance_stats) ? store.maintenance_stats : {}
+        remaining = stats[:expired]
+
+        puts "a2a-rails Task prune: deleted=#{total} batches=#{batches}" +
+          (remaining.nil? ? "" : " expired_remaining=#{remaining}")
+      rescue ArgumentError => error
+        abort error.message
+      end
+
+      desc "Print aggregate a2a-rails Task maintenance counts"
+      task stats: :environment do
+        store = A2A::Rails.configuration.resolve_task_store
+        unless store.respond_to?(:maintenance_stats)
+          abort "Configured a2a-rails Task Store does not support maintenance stats"
+        end
+
+        stats = store.maintenance_stats
+        puts [
+          "a2a-rails Task stats:",
+          "total=#{stats.fetch(:total)}",
+          "active=#{stats.fetch(:active)}",
+          "terminal=#{stats.fetch(:terminal)}",
+          "expired=#{stats.fetch(:expired)}"
+        ].join(" ")
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: a2a-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - cuichangquan
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: agent2agent
@@ -43,6 +43,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  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
@@ -97,6 +117,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :development
+  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
@@ -125,6 +165,46 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
 description: Expose Rails applications as A2A agents while keeping protocol SDK details
   behind an internal adapter boundary.
 executables: []
@@ -141,28 +221,39 @@ files:
 - lib/a2a-rails.rb
 - lib/a2a/rails/agent.rb
 - lib/a2a/rails/agent_card/builder.rb
+- lib/a2a/rails/agent_card/security.rb
 - lib/a2a/rails/agent_card/validator.rb
+- lib/a2a/rails/authentication.rb
 - lib/a2a/rails/configuration.rb
 - lib/a2a/rails/dispatcher.rb
 - lib/a2a/rails/engine.rb
 - lib/a2a/rails/errors.rb
+- lib/a2a/rails/execution_plan.rb
+- lib/a2a/rails/file_artifact.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/request_guard.rb
 - lib/a2a/rails/runtime.rb
 - lib/a2a/rails/skill.rb
 - lib/a2a/rails/task.rb
+- lib/a2a/rails/task/active_record_store.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/task_execution_arguments.rb
+- lib/a2a/rails/task_execution_job.rb
 - lib/a2a/rails/version.rb
 - lib/generators/a2a/rails/agent_generator.rb
 - lib/generators/a2a/rails/install_generator.rb
+- lib/generators/a2a/rails/task_store_generator.rb
 - lib/generators/a2a/rails/templates/agent.rb.tt
+- lib/generators/a2a/rails/templates/create_a2a_rails_tasks.rb.tt
 - lib/generators/a2a/rails/templates/initializer.rb.tt
+- lib/tasks/a2a_rails_tasks.rake
 homepage: https://github.com/cuichangquan/a2a-rails
 licenses:
 - MIT
@@ -186,7 +277,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.4
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails-native integration for exposing Rails applications as A2A agents
 test_files: []