a2a-rb 0.1.1

data/lib/a2a/security_scheme/mutual_tls.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module A2A
+  module SecurityScheme
+    class MutualTLS
+      attr_reader :description
+
+      def initialize(description: nil)
+        @description = description
+      end
+
+      def self.from_h(hash)
+        new(description: hash["description"])
+      end
+
+      def to_h
+        {
+          "mtlsSecurityScheme" => {
+            "description" => description
+          }.compact
+        }
+      end
+    end
+  end
+end

data/lib/a2a/security_scheme/oauth2.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module A2A
+  module SecurityScheme
+    class OAuth2
+      attr_reader :flows, :oauth2_metadata_url, :description
+
+      FLOW_TYPES = [
+        OAuthFlow::AuthorizationCode,
+        OAuthFlow::ClientCredentials,
+        OAuthFlow::DeviceCode
+      ].freeze
+
+      def initialize(flows:, oauth2_metadata_url: nil, description: nil)
+        unless flows.is_a?(Hash) && flows.size == 1 && FLOW_TYPES.any? { |t| flows.values.first.is_a?(t) }
+          raise ArgumentError, "flows must be a Hash with exactly one OAuthFlow entry"
+        end
+
+        @flows = flows
+        @oauth2_metadata_url = oauth2_metadata_url
+        @description = description
+      end
+
+      def self.from_h(hash)
+        new(
+          flows: OAuthFlow.from_h(hash.fetch("flows")),
+          oauth2_metadata_url: hash["oauth2MetadataUrl"],
+          description: hash["description"]
+        )
+      end
+
+      def to_h
+        {
+          "oauth2SecurityScheme" => {
+            "flows" => serialize_flows,
+            "oauth2MetadataUrl" => oauth2_metadata_url,
+            "description" => description
+          }.compact
+        }
+      end
+
+      private
+
+      def serialize_flows
+        flows.each_with_object({}) do |(key, flow), hash|
+          protocol_key = key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+          hash[protocol_key] = flow.to_h
+        end
+      end
+    end
+  end
+end

data/lib/a2a/security_scheme/open_id_connect.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module A2A
+  module SecurityScheme
+    class OpenIDConnect
+      attr_reader :open_id_connect_url, :description
+
+      def initialize(open_id_connect_url:, description: nil)
+        @open_id_connect_url = open_id_connect_url
+        @description = description
+      end
+
+      def self.from_h(hash)
+        new(
+          open_id_connect_url: hash.fetch("openIdConnectUrl"),
+          description: hash["description"],
+        )
+      end
+
+      def to_h
+        {
+          "openIdConnectSecurityScheme" => {
+            "openIdConnectUrl" => open_id_connect_url,
+            "description" => description
+          }.compact
+        }
+      end
+    end
+  end
+end

data/lib/a2a/security_scheme.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "security_scheme/api_key"
+require_relative "security_scheme/http_auth"
+require_relative "security_scheme/oauth2"
+require_relative "security_scheme/open_id_connect"
+require_relative "security_scheme/mutual_tls"
+
+module A2A
+  module SecurityScheme
+    BUILDERS = {
+      "apiKeySecurityScheme" => ->(v) { APIKey.from_h(v) },
+      "httpAuthSecurityScheme" => ->(v) { HTTPAuth.from_h(v) },
+      "oauth2SecurityScheme" => ->(v) { OAuth2.from_h(v) },
+      "openIdConnectSecurityScheme" => ->(v) { OpenIDConnect.from_h(v) },
+      "mtlsSecurityScheme" => ->(v) { MutualTLS.from_h(v) }
+    }.freeze
+
+    def self.from_h(hash)
+      key, builder = BUILDERS.find { |k, _| hash.key?(k) }
+      raise ArgumentError, "unknown SecurityScheme: #{hash.keys.inspect}" unless key
+
+      builder.call(hash[key])
+    end
+  end
+end

data/lib/a2a/streaming/artifact_update_event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module A2A
+  module Streaming
+    class ArtifactUpdateEvent
+      attr_reader :task_id, :context_id, :artifact, :append, :last_chunk, :metadata
+
+      def initialize(task_id:, context_id:, artifact:, **kwargs)
+        @task_id = task_id
+        @context_id = context_id
+        @artifact = artifact
+        @append = kwargs[:append] || false
+        @last_chunk = kwargs[:last_chunk] || false
+        @metadata = kwargs[:metadata]
+      end
+
+      def to_h
+        {
+          "taskId" => task_id,
+          "contextId" => context_id,
+          "artifact" => artifact.to_h,
+          "append" => append,
+          "lastChunk" => last_chunk,
+          "metadata" => metadata
+        }.compact
+      end
+
+      def self.from_h(hash)
+        new(
+          task_id: hash.fetch("taskId"),
+          context_id: hash.fetch("contextId"),
+          artifact: Artifact.from_h(hash.fetch("artifact")),
+          append: hash["append"],
+          last_chunk: hash["lastChunk"],
+          metadata: hash["metadata"]
+        )
+      end
+    end
+  end
+end

data/lib/a2a/streaming/response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module A2A
+  module Streaming
+    class Response
+      PAYLOAD_TYPES = {
+        task: Task,
+        message: Message,
+        status_update: StatusUpdateEvent,
+        artifact_update: ArtifactUpdateEvent
+      }.freeze
+
+      BUILDERS = {
+        "task" => ->(v) { new(:task, Task.from_h(v)) },
+        "message" => ->(v) { new(:message, Message.from_h(v)) },
+        "statusUpdate" => ->(v) { new(:status_update, StatusUpdateEvent.from_h(v)) },
+        "artifactUpdate" => ->(v) { new(:artifact_update, ArtifactUpdateEvent.from_h(v)) }
+      }.freeze
+
+      attr_reader :type, :payload
+
+      def initialize(type, payload)
+        expected = PAYLOAD_TYPES.fetch(type) { raise ArgumentError, "unknown type: #{type.inspect}" }
+        raise TypeError, "payload must be a #{expected}" unless payload.is_a?(expected)
+
+        @type = type
+        @payload = payload
+      end
+
+      def self.from_h(hash)
+        key, builder = BUILDERS.find { |k, _| hash.key?(k) }
+        raise ArgumentError, "unrecognised StreamResponse keys: #{hash.keys.inspect}" unless key
+
+        builder.call(hash[key])
+      end
+
+      WIRE_KEYS = {
+        task: "task",
+        message: "message",
+        status_update: "statusUpdate",
+        artifact_update: "artifactUpdate"
+      }.freeze
+
+      def to_h
+        { WIRE_KEYS.fetch(type) => payload.to_h }
+      end
+
+      def task?
+        type == :task
+      end
+
+      def message?
+        type == :message
+      end
+
+      def status_update?
+        type == :status_update
+      end
+
+      def artifact_update?
+        type == :artifact_update
+      end
+    end
+  end
+end

data/lib/a2a/streaming/sse_parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module A2A
+  module Streaming
+    module SseParser
+      # Parses a stream of SSE lines, yielding one Streaming::Response per
+      # logical event (blank-line delimited, multi-line data: concatenated).
+      def self.each(io, &block)
+        buffer = +""
+
+        io.each_line do |line|
+          line = line.chomp
+
+          if line.empty?
+            emit(buffer, &block) unless buffer.empty?
+            buffer = +""
+          elsif line.start_with?("data:")
+            # SSE spec: multiple data: lines are concatenated with U+000A
+            buffer << "\n" unless buffer.empty?
+            buffer << line.delete_prefix("data:").lstrip
+          end
+          # skip comment lines (":"), "event:", "id:", "retry:" fields
+        end
+
+        emit(buffer, &block) unless buffer.empty?
+      end
+
+      def self.emit(buffer)
+        data = buffer.strip
+        return if data == "[DONE]"
+
+        envelope = JSON.parse(data)
+        raise A2A.from_json_rpc_error(envelope["error"]) if envelope["error"]
+
+        event = Response.from_h(Hash(envelope["result"]))
+        yield event
+      end
+      private_class_method :emit
+    end
+  end
+end

data/lib/a2a/streaming/sse_writer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+
+module A2A
+  module Streaming
+    # Server-side counterpart to SseParser. Formats Streaming::Response objects
+    # (or raw hashes) as SSE frames ready to write to an HTTP response body.
+    module SSEWriter
+      # Returns the SSE wire representation of a Streaming::Response as a String.
+      # The result includes the trailing blank line that delimits SSE events.
+      def self.encode(response, id: nil)
+        payload = response.is_a?(Response) ? response.to_h : response
+        envelope = JSONRPCEnvelope.success(id: id, result: payload)
+        "data: #{JSON.generate(envelope)}\n\n"
+      end
+
+      # Encodes a JSON-RPC error as an SSE frame.
+      def self.encode_error(error, id: nil)
+        envelope = JSONRPCEnvelope.error(id: id, error: error)
+        "data: #{JSON.generate(envelope)}\n\n"
+      end
+    end
+  end
+end

data/lib/a2a/streaming/status_update_event.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module A2A
+  module Streaming
+    # The `final` field is a gem-level streaming-termination hint, not in the A2A proto.
+    # Servers that set "final": true signal this is the last status event for the task.
+    class StatusUpdateEvent
+      attr_reader :task_id, :context_id, :status, :final, :metadata
+
+      def initialize(context_id:, task_id:, status:, **kwargs)
+        raise TypeError, "status must be a Task::Status" unless status.is_a?(Task::Status)
+
+        @context_id = context_id
+        @task_id = task_id
+        @status = status
+        @final = kwargs.fetch(:final, false)
+        @metadata = kwargs[:metadata]
+      end
+
+      def final? = @final
+
+      def to_h
+        {
+          "taskId" => task_id,
+          "contextId" => context_id,
+          "status" => status.to_h,
+          "final" => final,
+          "metadata" => metadata
+        }.compact
+      end
+
+      def self.from_h(hash)
+        new(
+          task_id: hash.fetch("taskId"),
+          context_id: hash.fetch("contextId"),
+          status: Task::Status.from_h(hash.fetch("status")),
+          final: hash.fetch("final", false),
+          metadata: hash["metadata"]
+        )
+      end
+    end
+  end
+end

data/lib/a2a/streaming/subscription.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module A2A
+  module Streaming
+    class Subscription
+      include Enumerable
+
+      def initialize(io)
+        @io = io
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        SseParser.each(reader) do |event|
+          yield event
+          break if terminal?(event)
+        end
+      end
+
+      private
+
+      # Net::HTTPResponse streams via read_body; plain IO responds to each_line.
+      def reader
+        return @io unless @io.respond_to?(:read_body)
+
+        ChunkedReader.new(@io)
+      end
+
+      def terminal?(event)
+        case event.type
+        when :status_update
+          payload = event.payload
+          payload.final? || Task::State.terminal?(payload.status.state)
+        when :task
+          Task::State.terminal?(event.payload.status.state)
+        else
+          false
+        end
+      end
+
+      # Wraps Net::HTTPResponse so SseParser can call each_line on it.
+      class ChunkedReader
+        def initialize(response)
+          @response = response
+        end
+
+        def each_line(&block)
+          @response.read_body do |chunk|
+            chunk.each_line(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/a2a/streaming.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "streaming/status_update_event"
+require_relative "streaming/artifact_update_event"
+require_relative "streaming/response"
+require_relative "streaming/sse_parser"
+require_relative "streaming/subscription"
+
+module A2A
+  module Streaming
+  end
+end

data/lib/a2a/task/state.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module A2A
+  class Task
+    module State
+      UNSPECIFIED    = "TASK_STATE_UNSPECIFIED"
+      SUBMITTED      = "TASK_STATE_SUBMITTED"
+      WORKING        = "TASK_STATE_WORKING"
+      INPUT_REQUIRED = "TASK_STATE_INPUT_REQUIRED"
+      AUTH_REQUIRED  = "TASK_STATE_AUTH_REQUIRED"
+      COMPLETED      = "TASK_STATE_COMPLETED"
+      FAILED         = "TASK_STATE_FAILED"
+      CANCELED       = "TASK_STATE_CANCELED"
+      REJECTED       = "TASK_STATE_REJECTED"
+
+      ALL = [UNSPECIFIED, SUBMITTED, WORKING, INPUT_REQUIRED, AUTH_REQUIRED,
+             COMPLETED, FAILED, CANCELED, REJECTED].freeze
+
+      TERMINAL  = [COMPLETED, FAILED, CANCELED, REJECTED].freeze
+      RESUMABLE = [INPUT_REQUIRED, AUTH_REQUIRED].freeze
+
+      def self.valid?(value)
+        ALL.include?(value)
+      end
+
+      def self.terminal?(value)
+        TERMINAL.include?(value)
+      end
+    end
+  end
+end

data/lib/a2a/task/status.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module A2A
+  class Task
+    class Status
+      attr_reader :state, :message, :timestamp
+
+      def initialize(state:, message: nil, timestamp: nil)
+        @state = state
+        @message = message
+        @timestamp = timestamp
+      end
+
+      def self.from_h(hash)
+        new(
+          state: hash.fetch("state"),
+          message: hash["message"] && Message.from_h(hash["message"]),
+          timestamp: hash["timestamp"]
+        )
+      end
+
+      def to_h
+        {
+          "state" => state,
+          "message" => message&.to_h,
+          "timestamp" => timestamp
+        }.compact
+      end
+
+      def terminal?
+        Task::State.terminal?(state)
+      end
+    end
+  end
+end

data/lib/a2a/task.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "task/state"
+require_relative "task/status"
+
+module A2A
+  class Task
+    attr_reader :id, :context_id, :status, :artifacts, :history, :metadata
+
+    def initialize(id:, status:, **kwargs)
+      raise TypeError, "status must be a Task::Status" unless status.is_a?(Task::Status)
+
+      @id = id
+      @status = status
+      @context_id = kwargs[:context_id]
+      @artifacts = kwargs[:artifacts]
+      @history = kwargs[:history]
+      @metadata = kwargs[:metadata]
+    end
+
+    def self.from_h(hash)
+      new(
+        id: hash.fetch("id"),
+        context_id: hash["contextId"],
+        status: Task::Status.from_h(hash.fetch("status")),
+        artifacts: Array(hash["artifacts"]).map { Artifact.from_h(_1) },
+        history: Array(hash["history"]).map { Message.from_h(_1) },
+        metadata: hash["metadata"]
+      )
+    end
+
+    def terminal?
+      status.terminal?
+    end
+
+    # Returns a new Task with the status transitioned to `state`.
+    # Optionally attaches a status message and ISO-8601 timestamp.
+    # Raises ArgumentError for unknown states; raises TaskNotCancelableError
+    # when trying to transition away from a terminal state.
+    def transition_to(state, message: nil, timestamp: nil)
+      raise ArgumentError, "unknown state: #{state.inspect}" unless Task::State.valid?(state)
+      raise TaskNotCancelableError, "task #{id} is already in terminal state #{status.state}" if terminal?
+
+      new_status = Task::Status.new(state: state, message: message, timestamp: timestamp)
+      Task.new(
+        id: id,
+        context_id: context_id,
+        status: new_status,
+        artifacts: artifacts,
+        history: history,
+        metadata: metadata
+      )
+    end
+
+    def to_h
+      {
+        "id" => id,
+        "contextId" => context_id,
+        "status" => status.to_h,
+        "artifacts" => artifacts&.map(&:to_h),
+        "history" => history&.map(&:to_h),
+        "metadata" => metadata
+      }.compact
+    end
+  end
+end

data/lib/a2a/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module A2A
+  VERSION = "0.1.1"
+  SPEC_VERSION = "1.0"
+end

data/lib/a2a/versioning.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module A2A
+  module Versioning
+    CURRENT = SPEC_VERSION
+    SUPPORTED = [CURRENT].freeze
+
+    # Returns the normalized Major.Minor string from a version value.
+    # Strips any patch segment so "1.0.2" is treated as "1.0".
+    def self.normalize(version)
+      parts = version.to_s.split(".")
+      "#{parts[0]}.#{parts[1]}"
+    end
+
+    def self.supported?(version)
+      SUPPORTED.include?(version.to_s)
+    end
+
+    # Raises VersionNotSupportedError when the version is not in SUPPORTED.
+    # Returns the normalized version string when valid.
+    def self.validate!(version)
+      v = normalize(version)
+      raise VersionNotSupportedError, "unsupported A2A version: #{v}" unless supported?(v)
+
+      v
+    end
+  end
+end

data/lib/a2a.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "a2a/version"
+require_relative "a2a/task"
+require_relative "a2a/role"
+require_relative "a2a/part"
+require_relative "a2a/oauth_flow"
+require_relative "a2a/security_scheme"
+require_relative "a2a/security_requirement"
+require_relative "a2a/push_notification"
+require_relative "a2a/message"
+require_relative "a2a/artifact"
+require_relative "a2a/streaming"
+require_relative "a2a/agent_extension"
+require_relative "a2a/agent_interface"
+require_relative "a2a/agent_capabilities"
+require_relative "a2a/agent_provider"
+require_relative "a2a/agent_skill"
+require_relative "a2a/agent_card"
+require_relative "a2a/versioning"
+require_relative "a2a/protocol/json_rpc"
+require_relative "a2a/protocol/http_json"
+require_relative "a2a/operation"
+require_relative "a2a/client"
+require_relative "a2a/discovery"
+require_relative "a2a/json_rpc_envelope"
+require_relative "a2a/streaming/sse_writer"
+require_relative "a2a/operation/send_message_request"
+
+module A2A
+  class Error < StandardError
+    attr_reader :code, :details
+
+    def initialize(message, code: nil, details: nil)
+      super(message)
+
+      @code    = code
+      @details = details
+    end
+  end
+
+  # Transport / HTTP errors
+  class TransportError < Error; end
+  class AuthenticationError < Error; end
+  class AuthorizationError < Error; end
+  class ValidationError < Error; end
+
+  # Standard JSON-RPC errors
+  class JSONParseError < Error; end
+  class InvalidRequestError < Error; end
+  class MethodNotFoundError < Error; end
+  class InvalidParamsError < Error; end
+  class InternalError < Error; end
+
+  # A2A protocol errors
+  class TaskNotFoundError < Error; end
+  class TaskNotCancelableError < Error; end
+  class PushNotificationNotSupportedError < Error; end
+  class UnsupportedOperationError < Error; end
+  class ContentTypeNotSupportedError < Error; end
+  class InvalidAgentResponseError < Error; end
+  class ExtendedAgentCardNotConfiguredError < Error; end
+  class ExtensionSupportRequiredError < Error; end
+  class VersionNotSupportedError < Error; end
+
+  CODE_MAP = {
+    -32700 => JSONParseError,
+    -32600 => InvalidRequestError,
+    -32601 => MethodNotFoundError,
+    -32602 => InvalidParamsError,
+    -32603 => InternalError,
+    -32001 => TaskNotFoundError,
+    -32002 => TaskNotCancelableError,
+    -32003 => PushNotificationNotSupportedError,
+    -32004 => UnsupportedOperationError,
+    -32005 => ContentTypeNotSupportedError,
+    -32006 => InvalidAgentResponseError,
+    -32007 => ExtendedAgentCardNotConfiguredError,
+    -32008 => ExtensionSupportRequiredError,
+    -32009 => VersionNotSupportedError
+  }.freeze
+
+  def self.from_json_rpc_error(hash)
+    (CODE_MAP[hash["code"]] || Error).new(
+      hash["message"] || "unknown A2A error",
+      code: hash["code"],
+      details: hash["data"]
+    )
+  end
+end