a2a 0.1.0.pre → 0.2.0

data/lib/a2a/types/protocol_struct.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+
+module A2A
+  # Base class for all A2A struct objects
+  # @!visibility private
+  class ProtocolStruct < Dry::Struct
+    include Extensions::CaseTransformation
+    include Extensions::JSONDeserialization
+  end
+end

data/lib/a2a/types/push_notification_authentication_info.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines authentication details for a push notification endpoint.
+  class PushNotificationAuthenticationInfo < ProtocolStruct
+    # @return [Array<String>] A list of supported authentication schemes (e.g., 'Basic', 'Bearer').
+    attribute :schemes, Types::Array.of(Types::String)
+
+    # @return [String, nil] Optional credentials required by the push notification endpoint.
+    attribute? :credentials, Types::String.optional
+  end
+end

data/lib/a2a/types/push_notification_config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines the configuration for setting up push notifications for task updates.
+  class PushNotificationConfig < ProtocolStruct
+    # @return [String, nil] A unique identifier (e.g. UUID) for the push notification configuration, set by the client
+    #   to support multiple notification callbacks.
+    attribute? :id, Types::String.optional
+
+    # @return [URI] The callback URL where the agent should send push notifications.
+    attribute :url, Types::URI
+
+    # @return [String, nil] A unique token for this task or session to validate incoming push notifications.
+    attribute? :token, Types::String.optional
+
+    # @return [PushNotificationAuthenticationInfo, nil] Optional authentication details for the agent to use when
+    #   calling the notification URL.
+    attribute? :authentication, Types::Constructor(PushNotificationAuthenticationInfo).optional
+  end
+end

data/lib/a2a/types/push_notification_not_supported_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module A2A
+  # Error for unsupported push notifications (-32003)
+  #
+  # Raised when client attempts to use push notification features but the server agent
+  # does not support them (i.e., AgentCard.capabilities.pushNotifications is false).
+  #
+  # @api public
+  #
+  # @example Create a push notification not supported error
+  #   error = JSONRPC::PushNotificationNotSupportedError.new
+  #
+  class PushNotificationNotSupportedError < JSONRPC::Error
+    # Creates a new Push Notification Not Supported Error with code -32003
+    #
+    # @api public
+    #
+    # @example Create a push notification not supported error with default message
+    #   error = JSONRPC::PushNotificationNotSupportedError.new
+    #
+    # @example Create a push notification not supported error with exception details
+    #   error = JSONRPC::PushNotificationNotSupportedError.new(data: { capability: false }, 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 = 'Push Notification is not supported.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: ErrorCodes::PUSH_NOTIFICATION_NOT_SUPPORTED,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/a2a/types/request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # A discriminated union representing all possible JSON-RPC 2.0 requests supported by the A2A specification.
+  Request = SendMessageRequest |
+            SendStreamingMessageRequest |
+            GetTaskRequest |
+            CancelTaskRequest |
+            SetTaskPushNotificationConfigRequest |
+            GetTaskPushNotificationConfigRequest |
+            TaskResubscriptionRequest |
+            ListTaskPushNotificationConfigRequest |
+            DeleteTaskPushNotificationConfigRequest |
+            GetAuthenticatedExtendedCardRequest
+end

data/lib/a2a/types/security_scheme.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module A2A
+  # A discriminated union representing a security scheme that can be used to secure an agent's endpoints.
+  # This is a discriminated union type based on the OpenAPI 3.0 Security Scheme Object.
+  SecurityScheme = APIKeySecurityScheme |
+                   HTTPAuthSecurityScheme |
+                   OAuth2SecurityScheme |
+                   OpenIdConnectSecurityScheme |
+                   MutualTLSSecurityScheme
+end

data/lib/a2a/types/security_scheme_base.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module A2A
+  # Defines base properties shared by all security scheme objects.
+  class SecuritySchemeBase < ProtocolStruct
+    # @return [String, nil] An optional description for the security scheme.
+    attribute? :description, Types::String.optional
+  end
+end

data/lib/a2a/types/send_message_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a JSON-RPC request for the `message/send` method.
+  class SendMessageRequest < JSONRPC::Request
+    # @return [String] Method name for sending a message.
+    METHOD = 'message/send'
+
+    # @return [String] Method name for sending a message.
+    attribute :method, Types::String.constant(METHOD)
+
+    # @return [MessageSendParams] Parameters for sending a message.
+    attribute :params, Types::Constructor(MessageSendParams)
+
+    # @return [String] Method name for sending a message.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/send_message_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module A2A
+  # Response to a `message/send` request.
+  # Returns either a direct Message reply or the initial Task object.
+  class SendMessageResponse < JSONRPC::Response
+    # @return [Message, Task, nil] The result, which can be a direct reply Message or the initial Task object.
+    attribute? :result, Types::Any.optional
+
+    # @return [JSONRPC::Error, nil] Error information if the request failed.
+    attribute? :error, Types::Constructor(JSONRPC::Error).optional
+  end
+end

data/lib/a2a/types/send_streaming_message_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a JSON-RPC request for the `message/stream` method.
+  class SendStreamingMessageRequest < JSONRPC::Request
+    # @return [String] Method name for streaming a message.
+    METHOD = 'message/stream'
+
+    # @return [String] Method name for streaming a message.
+    attribute :method, Types::String.constant(METHOD)
+
+    # @return [MessageSendParams] Parameters for streaming a message.
+    attribute :params, Types::Constructor(MessageSendParams)
+
+    # @return [String] Method name for streaming a message.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/send_streaming_message_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Response to a `message/stream` request.
+  # The server may send multiple response objects for a single request.
+  # Returns a Message, Task, or streaming update events.
+  class SendStreamingMessageResponse < JSONRPC::Response
+    # @return [Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, nil]
+    #   The result, which can be a Message, Task, or streaming update event.
+    attribute? :result, Types::Any.optional
+
+    # @return [JSONRPC::Error, nil] Error information if the request failed.
+    attribute? :error, Types::Constructor(JSONRPC::Error).optional
+  end
+end

data/lib/a2a/types/set_task_push_notification_config_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a JSON-RPC request for the `tasks/pushNotificationConfig/set` method.
+  class SetTaskPushNotificationConfigRequest < JSONRPC::Request
+    # @return [String] Method name for setting task push notification configuration.
+    METHOD = 'tasks/pushNotificationConfig/set'
+
+    # @return [String] Method name for setting task push notification configuration.
+    attribute :method, Types::String.constant(METHOD)
+
+    # @return [TaskPushNotificationConfig] Parameters for setting the push notification configuration.
+    attribute :params, Types::Constructor(TaskPushNotificationConfig)
+
+    # @return [String] Method name for setting task push notification configuration.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/set_task_push_notification_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Request to set or update the push notification config for a task.
+  class SetTaskPushNotificationRequest < JSONRPC::Request
+    # @return [String] Method name for setting a task notifications.
+    METHOD = 'tasks/pushNotificationConfig/set'
+
+    # @return [String] Method name for setting a task notifications.
+    attribute :method, Types::String.constant(METHOD)
+
+    # @return [TaskPushNotificationConfig] Parameters for the set task push notification method.
+    attribute :params, Types::Constructor(TaskPushNotificationConfig)
+
+    # @return [String] Method name for setting a task notifications.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/set_task_push_notification_response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Response to a `tasks/pushNotificationConfig/set` request. Contains the TaskPushNotificationConfig or an error.
+  class SetTaskPushNotificationResponse < JSONRPC::Response
+    # @return [TaskPushNotificationConfig, nil] The push notification config if successful.
+    attribute? :result, Types::Constructor(TaskPushNotificationConfig).optional
+
+    # @return [JSONRPC::Error, nil] Error information if the request failed.
+    attribute? :error, Types::Constructor(JSONRPC::Error).optional
+  end
+end

data/lib/a2a/types/task.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a single, stateful operation or conversation between a client and an agent.
+  class Task < ProtocolStruct
+    # @return [String] A unique identifier (e.g. UUID) for the task, generated by the server for a new task.
+    attribute :id, Types::String
+
+    # @return [String] A server-generated unique identifier (e.g. UUID) for maintaining context across multiple related
+    #   tasks or interactions.
+    attribute :context_id, Types::String
+
+    # @return [TaskStatus] The current status of the task, including its state and a descriptive message.
+    attribute :status, Types::Constructor(TaskStatus)
+
+    # @return [Array<Message>, nil] An array of messages exchanged during the task, representing the conversation
+    #   history.
+    attribute? :history, Types::Array.of(Types::Constructor(Message)).optional
+
+    # @return [Array<Artifact>, nil] A collection of artifacts generated by the agent during the execution of the task.
+    attribute? :artifacts, Types::Array.of(Types::Constructor(Artifact)).optional
+
+    # @return [Hash, nil] Optional metadata for extensions. The key is an extension-specific identifier.
+    attribute? :metadata, Types::Hash.optional
+
+    # @return [String] The type of this object, used as a discriminator. Always 'task' for a Task.
+    attribute :kind, Types::String.constant('task')
+  end
+end

data/lib/a2a/types/task_artifact_update_event.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module A2A
+  # An event sent by the agent to notify the client that an artifact has been
+  # generated or updated. This is typically used in streaming models.
+  class TaskArtifactUpdateEvent < ProtocolStruct
+    # @return [String] The ID of the task this artifact belongs to.
+    attribute :task_id, Types::String
+
+    # @return [String] The context ID associated with the task.
+    attribute :context_id, Types::String
+
+    # @return [String] The type of this event, used as a discriminator. Always 'artifact-update'.
+    attribute :kind, Types::String.constant('artifact-update')
+
+    # @return [Artifact] The artifact that was generated or updated.
+    attribute :artifact, Types::Constructor(Artifact)
+
+    # @return [Boolean, nil] If true, the content of this artifact should be appended to a previously sent artifact
+    #   with the same ID.
+    attribute? :append, Types::Bool.optional
+
+    # @return [Boolean, nil] If true, this is the final chunk of the artifact.
+    attribute? :last_chunk, Types::Bool.optional
+
+    # @return [Hash, nil] Optional metadata for extensions.
+    attribute? :metadata, Types::Hash.optional
+  end
+end

data/lib/a2a/types/task_id_params.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Basic parameters used for task ID operations.
+  class TaskIdParams < ProtocolStruct
+    # @return [String] The unique identifier of the task.
+    attribute :id, Types::String
+
+    # @return [Hash, nil] Optional metadata to include with the operation.
+    attribute? :metadata, Types::Hash.optional
+  end
+end

data/lib/a2a/types/task_not_cancelable_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module A2A
+  # Error non-cancelable tasks (-32002)
+  #
+  # Raised when a task cannot be canceled. An attempt was made to cancel a task that is not in a cancelable state
+  # (e.g., it has already reached a terminal state like completed, failed, or canceled).
+  #
+  # @api public
+  #
+  # @example Create a task not cancelable error
+  #   error = JSONRPC::Errors::TaskNotCancelableError.new
+  #
+  class TaskNotCancelableError < JSONRPC::Error
+    # Creates a new Task Not Cancelable Error with code -32002
+    #
+    # @api public
+    #
+    # @example Create a task not cancelable error with default message
+    #   error = JSONRPC::TaskNotCancelableError.new
+    #
+    # @example Create a task not cancelable error with exception details
+    #   error = JSONRPC::TaskNotCancelableError.new(data: { exception: 'Task reached terminal state' }, 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 = 'Task cannot be canceled.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: ErrorCodes::TASK_NOT_CANCELABLE,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/a2a/types/task_not_found_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module A2A
+  # Error for missing tasks (-32001)
+  #
+  # Raised when the specified task ID does not correspond to an existing or active task.
+  # It might be invalid, expired, or already completed and purged.
+  #
+  # @api public
+  #
+  # @example Create a task not found error
+  #   error = JSONRPC::TaskNotFoundError.new
+  #
+  class TaskNotFoundError < JSONRPC::Error
+    # Creates a new Task Not Found Error with code -32001
+    #
+    # @api public
+    #
+    # @example Create a task not found error with default message
+    #   error = JSONRPC::TaskNotFoundError.new
+    #
+    # @example Create a task not found error with exception details
+    #   error = JSONRPC::TaskNotFoundError.new(data: { task_id: 'invalid-id' }, 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 = 'Task not found.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: ErrorCodes::TASK_NOT_FOUND,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/a2a/types/task_push_notification_config.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents the push notification information associated with a specific task ID.
+  class TaskPushNotificationConfig < ProtocolStruct
+    # @return [String] The ID of the task the notification config is associated with.
+    attribute :id, Types::String
+
+    # @return [PushNotificationConfig] The push notification configuration details.
+    attribute :push_notification_config, Types::Constructor(PushNotificationConfig)
+  end
+end

data/lib/a2a/types/task_query_params.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module A2A
+  # Parameters used for querying task-related information by ID.
+  class TaskQueryParams < TaskIdParams
+    # @return [Integer, nil] Optional history length to retrieve for the task.
+    attribute? :history_length, Types::Integer.optional
+  end
+end

data/lib/a2a/types/task_resubscription_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  # Request to resubscribe to updates for a task after a connection interruption.
+  class TaskResubscriptionRequest < JSONRPC::Request
+    # @return [String] Method name for resubscribing to task updates.
+    METHOD = 'tasks/resubscribe'
+
+    # @return [String] Method name for resubscribing to task updates.
+    attribute :method, Types::String.constant(METHOD)
+
+    # @return [TaskQueryParams] Parameters for the task resubscription method.
+    attribute :params, Types::Constructor(TaskQueryParams)
+
+    # @return [String] Method name for resubscribing to task updates.
+    def method = attributes[:method]
+  end
+end

data/lib/a2a/types/task_state.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module A2A
+  # The current state of the task
+  TaskState = Types::String.enum('submitted', 'working', 'input-required', 'completed', 'canceled', 'failed',
+                                 'rejected', 'auth-required', 'unknown')
+end

data/lib/a2a/types/task_status.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents the status of a task at a specific point in time.
+  class TaskStatus < ProtocolStruct
+    # @return [String] The current state of the task.
+    attribute :state, TaskState
+
+    # @return [Message, nil] An optional message associated with the current status.
+    attribute? :message, Types::Constructor(Message).optional
+
+    # @return [DateTime, nil] The timestamp when this status was recorded (ISO 8601 format).
+    attribute? :timestamp, Types::JSON::DateTime.optional
+  end
+end

data/lib/a2a/types/task_status_update_event.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module A2A
+  # An event sent by the agent to notify the client of a change in a task's status.
+  # This is typically used in streaming or subscription models.
+  class TaskStatusUpdateEvent < ProtocolStruct
+    # @return [String] The ID of the task that was updated.
+    attribute :task_id, Types::String
+
+    # @return [String] The context ID associated with the task.
+    attribute :context_id, Types::String
+
+    # @return [String] The type of this event, used as a discriminator. Always 'status-update'.
+    attribute :kind, Types::String.constant('status-update')
+
+    # @return [TaskStatus] The new status of the task.
+    attribute :status, Types::Constructor(TaskStatus)
+
+    # @return [Boolean] If true, this is the final event in the stream for this interaction.
+    attribute :final, Types::Bool
+
+    # @return [Hash, nil] Optional metadata for extensions.
+    attribute? :metadata, Types::Hash.optional
+  end
+end

data/lib/a2a/types/text_part.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  # Represents a text segment within a message or artifact.
+  class TextPart < PartBase
+    # @return [String] The type of this part, used as a discriminator. Always 'text'.
+    attribute :kind, Types::String.constant('text')
+
+    # @return [String] The string content of the text part.
+    attribute :text, Types::String
+  end
+end

data/lib/a2a/types/transport_protocol.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module A2A
+  # Supported A2A transport protocols.
+  TransportProtocol = Types::String.enum('JSONRPC', 'GRPC', 'HTTP+JSON')
+end

data/lib/a2a/types/unsupported_operation_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module A2A
+  # Error for unsupported operations (-32004)
+  #
+  # Raised when the requested operation or a specific aspect of it (perhaps implied by parameters)
+  # is not supported by this server agent implementation. Broader than just method not found.
+  #
+  # @api public
+  #
+  # @example Create an unsupported operation error
+  #   error = JSONRPC::UnsupportedOperationError.new
+  #
+  class UnsupportedOperationError < JSONRPC::Error
+    # Creates a new Unsupported Operation Error with code -32004
+    #
+    # @api public
+    #
+    # @example Create an unsupported operation error with default message
+    #   error = JSONRPC::UnsupportedOperationError.new
+    #
+    # @example Create an unsupported operation error with exception details
+    #   error = JSONRPC::UnsupportedOperationError.new(data: { operation: 'streaming' }, 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 = 'This operation is not supported.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: ErrorCodes::UNSUPPORTED_OPERATION,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/a2a/types.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'dry-types'
+
+module A2A
+  # @!visibility private
+  module Types
+    include Dry.Types()
+
+    Dry::Types.define_builder(:constant) { |type, value| type.default(value).enum(value) }
+
+    # Custom URI type that accepts both String and URI objects
+    # and ensures the result is always a URI object
+    URI = Types.Constructor(::URI) do |value|
+      case value
+      when ::URI
+        value
+      when String
+        ::URI.parse(value)
+      else
+        raise ArgumentError, "Expected String or URI, got #{value.class}"
+      end
+    end
+  end
+end

data/lib/a2a/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module A2A
-  VERSION = '0.1.0.pre'
+  VERSION = '0.2.0'
 end

data/lib/a2a.rb

@@ -1,7 +1,36 @@
 # frozen_string_literal: true
 
-require_relative 'a2a/version'
+require 'dry/inflector'
+require 'zeitwerk'
+require 'jsonrpc'
+require 'a2a/rails/railtie' if defined?(Rails)
 
 # Encapsulates all the gem's logic
 module A2A
+  # @!visibility private
+  # @return [Dry::Inflector] The inflector instance used for camelizing keys
+  INFLECTOR = Dry::Inflector.new
 end
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  'a2a' => 'A2A',
+  'api_key_security_scheme' => 'APIKeySecurityScheme',
+  'authorization_code_oauth_flow' => 'AuthorizationCodeOAuthFlow',
+  'client_credentials_oauth_flow' => 'ClientCredentialsOAuthFlow',
+  'http_auth_security_scheme' => 'HTTPAuthSecurityScheme',
+  'implicit_oauth_flow' => 'ImplicitOAuthFlow',
+  'json_deserialization' => 'JSONDeserialization',
+  'jsonrpc_helpers' => 'JSONRPCHelpers',
+  'mutual_tls_security_scheme' => 'MutualTLSSecurityScheme',
+  'oauth2_security_scheme' => 'OAuth2SecurityScheme',
+  'oauth_flows' => 'OAuthFlows',
+  'openid_connect_security_scheme' => 'OpenIdConnectSecurityScheme',
+  'password_oauth_flow' => 'PasswordOAuthFlow',
+  'uri' => 'URI'
+)
+loader.collapse("#{__dir__}/a2a/types")
+loader.ignore("#{__dir__}/a2a/rails/railtie.rb")
+loader.enable_reloading
+loader.setup
+loader.eager_load