a2a 0.1.0.pre → 0.2.0

data/WARP.md

@@ -0,0 +1,115 @@
+# WARP.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+## Development Commands
+
+### Essential Commands
+```bash
+# Setup development environment
+bin/setup
+
+# Interactive console for experimentation
+bin/console
+
+# Install gem locally for testing
+bundle exec rake install
+
+# Run all tests
+bundle exec rspec
+
+# Run tests with coverage (opens HTML report)
+rake coverage
+
+# Lint code with RuboCop
+bundle exec rubocop
+
+# Auto-fix RuboCop offenses (safe only)
+bundle exec rubocop --autocorrect
+
+# Run comprehensive quality assurance
+rake qa
+```
+
+### Testing and Quality
+```bash
+# Run specific test file
+bundle exec rspec spec/a2a_spec.rb
+
+# Run tests with focus on failed specs
+bundle exec rspec --only-failures
+
+# Generate YARD documentation
+bundle exec yard
+
+# Type checking with Steep
+bundle exec steep check
+
+# Security audit
+bundle exec bundle-audit
+
+# Documentation coverage measurement
+rake yardstick_measure
+rake verify_measurements
+```
+
+### Development Workflow
+```bash
+# Watch files for changes (requires Guard)
+bundle exec guard
+
+# Build gem package
+bundle exec rake build
+
+# Release new version (updates version, creates tag, pushes to RubyGems)
+bundle exec rake release
+```
+
+### Claude AI Commands
+```bash
+# Update Gemfile dependencies with commit
+claude --print --verbose "/gemfile:update --commit"
+```
+
+## Architecture Overview
+
+### Core Structure
+- **A2A Protocol Implementation**: Ruby implementation of the Agent2Agent communication protocol
+- **Dry-Struct Based**: Uses `dry-struct` for typed data structures with validation
+- **Case Transformation**: Automatic conversion between snake_case (Ruby) and camelCase (JSON protocol)
+- **JSON-RPC Messages**: Full support for JSON-RPC request/response patterns
+
+### Key Components
+
+#### Extensions (`lib/a2a/extensions/`)
+- **CaseTransformation**: Handles snake_case ↔ camelCase conversion during serialization
+- **JSONDeserialization**: Enables creating objects directly from JSON strings
+- **AdditionalProperties**: Supports flexible schema with extra properties
+
+#### Types System (`lib/a2a/types/`)
+- Protocol-compliant data structures (requests, responses, agents, tasks, etc.)
+- All types inherit from `Dry::Struct` with validation
+- Support for additional properties beyond defined attributes
+
+### Development Environment
+- **Ruby Version**: 3.4+ required
+- **Type System**: RBS type definitions in `sig/` directory
+- **Testing**: RSpec with FactoryBot for test data
+- **Code Quality**: RuboCop with multiple plugins (performance, RSpec, factory_bot)
+- **Documentation**: YARD with 100% coverage requirement
+- **Security**: Bundler Audit integration
+- **CI/CD**: Overcommit hooks for pre-commit validation
+
+### Protocol Implementation Details
+The gem provides Ruby objects for all A2A protocol message types:
+- Task management (send, cancel, status)
+- Agent capabilities and authentication
+- File and artifact handling
+- Push notifications
+- Error handling with standardized codes
+
+All objects support:
+- Instantiation from hash data (with automatic key transformation)
+- JSON serialization with protocol-compliant camelCase keys
+- Type validation and additional property support
+- Parsing from JSON strings via `from_json` methods

data/lib/a2a/extensions/additional_properties.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module A2A
+  module Extensions
+    # Allows a dry-struct to have additional properties beyond the defined schema.
+    # Limitations: the +attributes+ method does not return additional properties.
+    module AdditionalProperties
+      # @!visibility private
+      # @return [Hash] Storage for additional properties not defined in the schema
+      attr_reader :additional_properties
+
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Initialize with empty additional properties
+      def initialize(*)
+        super
+        @additional_properties ||= {}
+      end
+
+      # Access additional properties via method_missing
+      #
+      # @param method_name [Symbol] Method name corresponding to property
+      # @param args [Array] Method arguments (unused)
+      #
+      # @return [Object, nil] Property value if found
+      #
+      def method_missing(method_name, *args)
+        if additional_properties.key?(method_name)
+          additional_properties[method_name]
+        else
+          super
+        end
+      end
+
+      # Indicate whether the object responds to the given method
+      #
+      # @param method_name [Symbol] Method name
+      # @param include_private [Boolean] Whether to include private methods
+      #
+      # @return [Boolean] Whether the object responds to the method
+      #
+      def respond_to_missing?(method_name, include_private = false)
+        additional_properties.key?(method_name) || super
+      end
+
+      # Convert the struct to a hash, including additional properties
+      #
+      # @return [Hash] All properties as a hash
+      #
+      def to_h
+        super.merge(additional_properties)
+      end
+
+      # Override the camelize method to handle additional properties correctly
+      #
+      # @param value [Object] The value to convert
+      #
+      # @return [Object] The value with camelized keys if applicable
+      #
+      def camelize(value)
+        case value
+        when Hash
+          value.to_h do |key, v|
+            [INFLECTOR.camelize_lower(key.to_s).to_sym, camelize(v)]
+          end
+        when Array
+          value.map { |item| camelize(item) }
+        else
+          value
+        end
+      end
+
+      # Class methods added to the class that includes AdditionalProperties
+      module ClassMethods
+        # Override the new method to handle additional properties
+        #
+        # @param hash [Hash, nil] Input hash including both schema and additional properties
+        #
+        # @return [Object] New instance with additional properties preserved
+        #
+        def new(hash = nil)
+          hash = {} if hash.nil?
+
+          # Convert all keys to symbols
+          input = hash.transform_keys(&:to_sym)
+
+          # Get schema keys
+          schema_keys = schema.keys.map(&:name)
+
+          # Split input into schema data and additional properties
+          schema_data = {}
+          additional_props = {}
+
+          input.each do |key, value|
+            snake_key = INFLECTOR.underscore(key.to_s).to_sym
+
+            if schema_keys.include?(snake_key)
+              schema_data[snake_key] = value
+            elsif schema_keys.include?(key)
+              schema_data[key] = value
+            else
+              # Store additional properties with snake_case keys
+              additional_props[snake_key] = value
+            end
+          end
+
+          # Create instance using schema data
+          instance = super(schema_data)
+
+          # Attach additional properties
+          instance.instance_variable_set(:@additional_properties, additional_props)
+
+          instance
+        end
+      end
+    end
+  end
+end

data/lib/a2a/extensions/case_transformation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module A2A
+  module Extensions
+    # Allows a dry-struct to be instantiated and serialized with camelCase keys.
+    module CaseTransformation
+      def self.included(base)
+        base.class_eval do
+          # Transform keys to snake_case symbols when initializing the struct
+          transform_keys { |key| INFLECTOR.underscore(key.to_s).to_sym }
+        end
+      end
+
+      # Converts hash keys from snake_case to camelCase recursively
+      #
+      # @param value [Object] The value to convert
+      #
+      # @return [Object] The value with camelized keys if applicable
+      #
+      def camelize(value)
+        case value
+        when Array
+          value.map { |item| camelize(item) }
+        when Hash
+          value.to_h do |key, v|
+            [INFLECTOR.camelize_lower(key.to_s).to_sym, camelize(v)]
+          end
+        else
+          value
+        end
+      end
+
+      # Serializes the object to JSON with an option for camelCase formatting
+      #
+      # @param camel_case [Boolean] Whether to convert keys to camelCase
+      #
+      # @return [String] JSON representation of the object
+      #
+      def to_json(camel_case: true, **)
+        data = to_h
+        data = camelize(data) if camel_case
+        data.to_json(**)
+      end
+    end
+  end
+end

data/lib/a2a/extensions/json_deserialization.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module A2A
+  module Extensions
+    # Provides JSON deserialization capabilities to a class
+    module JSONDeserialization
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods added to the class that includes JsonDeserialization
+      module ClassMethods
+        # Creates a new instance from a JSON string
+        #
+        # @param json [String] JSON string to parse
+        # @return [ProtocolStruct] A new instance of the appropriate class
+        #
+        # @example Create a Google Maps Agent Card from JSON
+        #   json_string = <<~JSON
+        #     {
+        #       "name": "Google Maps Agent",
+        #       "description": "Plan routes, remember places, and generate directions",
+        #       "url": "https://maps-agent.google.com",
+        #       "provider": {
+        #         "organization": "Google",
+        #         "url": "https://google.com"
+        #       },
+        #       "version": "1.0.0",
+        #       "capabilities": {
+        #         "streaming": true,
+        #         "pushNotifications": false
+        #       },
+        #       "skills": [
+        #         {
+        #           "id": "route-planner",
+        #           "name": "Route planning",
+        #           "description": "Helps plan routing between two locations"
+        #         }
+        #       ]
+        #     }
+        #   JSON
+        #   agent_card = A2A::AgentCard.from_json(json_string)
+        #
+        def from_json(json)
+          new(MultiJson.load(json, symbolize_keys: true))
+        end
+      end
+    end
+  end
+end

data/lib/a2a/types/agent_capabilities.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Describes the capabilities of an agent.
+  class AgentCapabilities < ProtocolStruct
+    # @return [Boolean] Indicates if the agent supports streaming responses.
+    attribute? :streaming, Types::Bool.default(false)
+
+    # @return [Boolean] Indicates if the agent supports push notification mechanisms.
+    attribute? :push_notifications, Types::Bool.default(false)
+
+    # @return [Boolean] Indicates if the agent supports providing state transition history.
+    attribute? :state_transition_history, Types::Bool.default(false)
+
+    # @return [Array<AgentExtension>, nil] A list of protocol extensions supported by the agent.
+    attribute? :extensions, Types::Array.of(Types::Constructor(AgentExtension)).optional
+  end
+end

data/lib/a2a/types/agent_card.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module A2A
+  # The AgentCard is a self-describing manifest for an agent. It provides essential
+  # metadata including the agent's identity, capabilities, skills, supported
+  # communication methods, and security requirements.
+  class AgentCard < ProtocolStruct
+    # @return [String] The version of the A2A protocol this agent supports.
+    attribute :protocol_version, Types::String.default('0.3.0')
+
+    # @return [String] A human-readable name for the agent.
+    attribute :name, Types::String
+
+    # @return [String] A human-readable description of the agent, assisting users and other agents
+    #   in understanding its purpose.
+    attribute :description, Types::String
+
+    # @return [URI] The preferred endpoint URL for interacting with the agent.
+    #   This URL MUST support the transport specified by 'preferred_transport'.
+    attribute :url, Types::URI
+
+    # @return [String] The transport protocol for the preferred endpoint (the main 'url' field).
+    #   If not specified, defaults to 'JSONRPC'.
+    attribute? :preferred_transport, Types::String.default('JSONRPC')
+
+    # @return [Array<AgentInterface>, nil] A list of additional supported interfaces (transport and URL combinations).
+    #   This allows agents to expose multiple transports, potentially at different URLs.
+    attribute? :additional_interfaces, Types::Array.of(Types::Constructor(AgentInterface)).optional
+
+    # @return [URI, nil] An optional URL to an icon for the agent.
+    attribute? :icon_url, Types::URI.optional
+
+    # @return [AgentProvider, nil] Information about the provider of the agent.
+    attribute? :provider, Types::Constructor(AgentProvider).optional
+
+    # @return [String] The agent's own version number. The format is defined by the provider.
+    attribute :version, Types::String
+
+    # @return [URI, nil] An optional URL to the agent's documentation.
+    attribute? :documentation_url, Types::URI.optional
+
+    # @return [AgentCapabilities] A declaration of optional capabilities supported by the agent.
+    attribute :capabilities, Types::Constructor(AgentCapabilities)
+
+    # @return [Hash<String, SecurityScheme>, nil] A declaration of the security schemes available to authorize requests.
+    #   The key is the scheme name. Follows the OpenAPI 3.0 Security Scheme Object.
+    attribute? :security_schemes, Types::Hash.map(Types::Symbol | Types::String, Types::Constructor(SecurityScheme)).optional
+
+    # @return [Array<Hash>, nil] A list of security requirement objects that apply to all agent interactions.
+    #   Each object lists security schemes that can be used. Follows the OpenAPI 3.0 Security Requirement Object.
+    attribute? :security, Types::Array.of(Types::Hash.map(Types::String | Types::Symbol, Types::Array.of(Types::String))).optional
+
+    # @return [Array<String>] Default set of supported input MIME types for all skills, which can be
+    #   overridden on a per-skill basis.
+    attribute :default_input_modes, Types::Array.of(Types::String)
+
+    # @return [Array<String>] Default set of supported output MIME types for all skills, which can be
+    #   overridden on a per-skill basis.
+    attribute :default_output_modes, Types::Array.of(Types::String)
+
+    # @return [Array<AgentSkill>] The set of skills, or distinct capabilities, that the agent can perform.
+    attribute :skills, Types::Array.of(Types::Constructor(AgentSkill))
+
+    # @return [Boolean] If true, the agent can provide an extended agent card with additional details
+    #   to authenticated users. Defaults to false.
+    attribute? :supports_authenticated_extended_card, Types::Bool.default(false)
+
+    # @return [Array<AgentCardSignature>, nil] JSON Web Signatures computed for this AgentCard.
+    attribute? :signatures, Types::Array.of(Types::Constructor(AgentCardSignature)).optional
+  end
+end

data/lib/a2a/types/agent_card_signature.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module A2A
+  # AgentCardSignature represents a JWS signature of an AgentCard.
+  # This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).
+  class AgentCardSignature < ProtocolStruct
+    # @return [String] The protected JWS header for the signature. This is a Base64url-encoded
+    #   JSON object, as per RFC 7515.
+    attribute :protected, Types::String
+
+    # @return [String] The computed signature, Base64url-encoded.
+    attribute :signature, Types::String
+
+    # @return [Hash, nil] The unprotected JWS header values.
+    attribute? :header, Types::Hash.optional
+  end
+end

data/lib/a2a/types/agent_extension.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module A2A
+  # A declaration of a protocol extension supported by an Agent.
+  class AgentExtension < ProtocolStruct
+    # @return [URI] The unique URI identifying the extension.
+    attribute :uri, Types::URI
+
+    # @return [String, nil] A human-readable description of how this agent uses the extension.
+    attribute? :description, Types::String.optional
+
+    # @return [Boolean] If true, the client must understand and comply with the extension's requirements
+    #   to interact with the agent.
+    attribute? :required, Types::Bool.default(false)
+
+    # @return [Hash, nil] Optional, extension-specific configuration parameters.
+    attribute? :params, Types::Hash.optional
+  end
+end

data/lib/a2a/types/agent_interface.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module A2A
+  # Declares a combination of a target URL and a transport protocol for interacting with the agent.
+  # This allows agents to expose the same functionality over multiple transport mechanisms.
+  class AgentInterface < ProtocolStruct
+    # @return [URI] The URL where this interface is available. Must be a valid absolute HTTPS URL in production.
+    attribute :url, Types::URI
+
+    # @return [String] The transport protocol supported at this URL.
+    attribute :transport, Types::String
+  end
+end

data/lib/a2a/types/agent_provider.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents the provider or organization behind an agent.
+  class AgentProvider < ProtocolStruct
+    # @return [String] The name of the organization providing the agent.
+    attribute :organization, Types::String
+
+    # @return [URI] A URL for the agent provider's website or relevant documentation.
+    attribute :url, Types::URI
+  end
+end

data/lib/a2a/types/agent_skill.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines a specific skill or capability offered by an agent.
+  class AgentSkill < ProtocolStruct
+    # @return [String] Unique identifier for the skill.
+    attribute :id, Types::String
+
+    # @return [String] Human-readable name of the skill.
+    attribute :name, Types::String
+
+    # @return [String] A detailed description of the skill, intended to help clients or users
+    #   understand its purpose and functionality.
+    attribute :description, Types::String
+
+    # @return [Array<String>] A set of keywords describing the skill's capabilities.
+    attribute :tags, Types::Array.of(Types::String)
+
+    # @return [Array<String>, nil] Optional list of example inputs or use cases for the skill.
+    attribute? :examples, Types::Array.of(Types::String).optional
+
+    # @return [Array<String>, nil] Optional list of input modes supported by this skill, overriding agent defaults.
+    attribute? :input_modes, Types::Array.of(Types::String).optional
+
+    # @return [Array<String>, nil] Optional list of output modes supported by this skill, overriding agent defaults.
+    attribute? :output_modes, Types::Array.of(Types::String).optional
+
+    # @return [Array<Hash>, nil] Security schemes necessary for the agent to leverage this skill.
+    #   As in the overall AgentCard.security, this list represents a logical OR of security
+    #   requirement objects. Each object is a set of security schemes that must be used together
+    #   (a logical AND).
+    attribute? :security, Types::Array.of(Types::Hash.map(Types::String, Types::Array.of(Types::String))).optional
+  end
+end

data/lib/a2a/types/api_key_security_scheme.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines a security scheme using an API key.
+  class APIKeySecurityScheme < SecuritySchemeBase
+    # @return [String] The type of the security scheme. Must be 'apiKey'.
+    attribute :type, Types::String.constant('apiKey')
+
+    # @return [String] The location of the API key.
+    attribute :in, Types::String.enum('query', 'header', 'cookie')
+
+    # @return [String] The name of the header, query, or cookie parameter to be used.
+    attribute :name, Types::String
+  end
+end

data/lib/a2a/types/artifact.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a file, data structure, or other resource generated by an agent during a task.
+  class Artifact < ProtocolStruct
+    # @return [String] A unique identifier (e.g. UUID) for the artifact within the scope of the task.
+    attribute :artifact_id, Types::String
+
+    # @return [String, nil] An optional, human-readable name for the artifact.
+    attribute? :name, Types::String.optional
+
+    # @return [String, nil] An optional, human-readable description of the artifact.
+    attribute? :description, Types::String.optional
+
+    # @return [Array<Part>] An array of content parts that make up the artifact.
+    attribute :parts, Types::Array.of(Types::Constructor(Part))
+
+    # @return [Hash, nil] Optional metadata for extensions. The key is an extension-specific identifier.
+    attribute? :metadata, Types::Hash.optional
+
+    # @return [Array<String>, nil] The URIs of extensions that are relevant to this artifact.
+    attribute? :extensions, Types::Array.of(Types::String).optional
+  end
+end

data/lib/a2a/types/authenticated_extended_card_not_configured_error.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module A2A
+  # Error for missing authenticated extended card configuration (-32007)
+  #
+  # Raised when the agent does not have an Authenticated Extended Card configured.
+  #
+  # @api public
+  #
+  # @example Create an authenticated extended card not configured error
+  #   error = JSONRPC::AuthenticatedExtendedCardNotConfiguredError.new
+  #
+  class AuthenticatedExtendedCardNotConfiguredError < JSONRPC::Error
+    # Creates a new Authenticated Extended Card Not Configured Error with code -32007
+    #
+    # @api public
+    #
+    # @example Create an authenticated extended card not configured error with default message
+    #   error = JSONRPC::AuthenticatedExtendedCardNotConfiguredError.new
+    #
+    # @example Create an authenticated extended card not configured error with exception details
+    #   error = JSONRPC::AuthenticatedExtendedCardNotConfiguredError.new(
+    #     data: { feature: 'extended_card' }, request_id: 1
+    #   )
+    #
+    # @param message [String] short description of the error
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    # @param request_id [String, Integer, nil] the request identifier
+    #
+    def initialize(
+      message = 'Authenticated Extended Card not configured.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: ErrorCodes::AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/a2a/types/authorization_code_oauth_flow.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines configuration details for the OAuth 2.0 Authorization Code flow.
+  class AuthorizationCodeOAuthFlow < ProtocolStruct
+    # @return [URI] The authorization URL to be used for this flow.
+    #   This MUST be a URL and use TLS.
+    attribute :authorization_url, Types::URI
+
+    # @return [URI] The token URL to be used for this flow.
+    #   This MUST be a URL and use TLS.
+    attribute :token_url, Types::URI
+
+    # @return [URI, nil] The URL to be used for obtaining refresh tokens.
+    #   This MUST be a URL and use TLS.
+    attribute? :refresh_url, Types::URI.optional
+
+    # @return [Hash] The available scopes for the OAuth2 security scheme. A map between the scope
+    #   name and a short description for it.
+    attribute :scopes, Types::Hash.map(Types::String, Types::String)
+  end
+end

data/lib/a2a/types/cancel_task_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Request to cancel a currently running task.
+  class CancelTaskRequest < JSONRPC::Request
+    # @return [String] Method name for canceling a task.
+    METHOD = 'tasks/cancel'
+
+    # @return [String] Method name for canceling a task.
+    attribute :method, Types::String.constant(METHOD)
+
+    # @return [TaskIdParams] Parameters for the cancel task method.
+    attribute :params, Types::Constructor(TaskIdParams)
+
+    # @return [String] Method name for canceling a task.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/cancel_task_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Response to a `tasks/cancel` request. Contains the updated Task object or an error.
+  class CancelTaskResponse < JSONRPC::Response
+    # @return [Task, nil] The canceled task information if successful.
+    attribute? :result, Types::Constructor(Task).optional
+
+    # @return [JSONRPC::Error, nil] Error information if the request failed.
+    attribute? :error, Types::Constructor(JSONRPC::Error).optional
+  end
+end