a2a-rb 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0b5296863ce5b960cf2b4a3f27c3f4e4e93399f93c13c003719437e62891582
+  data.tar.gz: 52641e6cf375bcf43392e178b3e06aa21e8dc77a2eda334ee3bb7e33ce598453
+SHA512:
+  metadata.gz: 99fbf4d17ac3d536da464f3893174c459ad63822e967b9c798840770eee9f255d72fc2270a90a4d3ef8b692fc943c902314705da510d23d181f73f4df480155d
+  data.tar.gz: 700d3a88eebecb34044067b1b55eb89b74d4c3ba11840ffc205c0e8f3027ccdc8389599d6fe2d0943c62db23f182ec738c96e5d3cd7f21b8fe212f31370ed5eb

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] — 2026-06-26\n\n### Added
+- wire up top-level A2A module with error classes and requires
+- add JSONRPCEnvelope for server-side request/response handling
+- add JSON-RPC and HTTP+JSON protocol bindings and client
+- add push notification config, dispatcher, and Rack receiver
+- add security schemes and OAuth flow types
+- add AgentCard, discovery, and agent metadata types
+- add streaming types and SSE parser/writer
+- add core data model (Task, Message, Artifact, Part types, Role)
+
+### Changed
+- pre-publish fixes (gemspec author, URLs, license, dev deps to Gemfile)
+- add conventional commits hook and automated changelog generation (release)
+- add rubocop config, ruby version pin, and gemspec
+
+### Other
+- update CLAUDE.md
+- add README, examples, changelog, and Claude harness
+- add full spec suite (595 examples)
+
+## [0.1.0] — 2026-06-17
+
+### Added
+- Initial gem scaffold (lib, spec, bin/console, bin/setup, gemspec)
+
+[Unreleased]: https://github.com/rafaelqfigueiredo/a2a-rb/compare/v0.1.1...HEAD
+[0.1.0]: https://github.com/rafaelqfigueiredo/a2a-rb/releases/tag/v0.1.0
+
+[0.1.1]: https://github.com/rafaelqfigueiredo/a2a-rb/compare/v0.1.0...v0.1.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Figueiredo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,311 @@
+# a2a-rb
+
+Ruby implementation of the [A2A protocol v1.0](https://a2a-protocol.org/latest/specification) — an open standard for agent-to-agent communication.
+
+The gem is a **data-model and serialisation library**: it models every message
+type from the A2A spec, provides a full client for calling remote agents, and
+includes protocol-level primitives for building server-side handlers. No HTTP
+server is bundled — mount it behind Rails, Sinatra, or any Rack application.
+
+- Ruby 3.4+
+- No runtime dependencies
+- Both JSON-RPC 2.0 and HTTP+JSON bindings
+
+## Installation
+
+```ruby
+# Gemfile
+gem "a2a-rb"
+```
+
+```bash
+bundle install
+```
+
+## Quick start
+
+```ruby
+require "a2a"
+
+# 1. Discover an agent
+card = A2A::Discovery.fetch("https://agent.example.com")
+
+# 2. Build a client (negotiates the best available protocol binding)
+client = A2A::Client.from_agent_card(card)
+
+# 3. Send a message
+result = client.send_message(
+  A2A::Message.new(
+    id: SecureRandom.uuid,
+    role: A2A::Role::USER,
+    parts: [A2A::Part::Text.new(text: "Summarise this document.")]
+  )
+)
+
+case result
+when A2A::Task    then puts "Task #{result.id}: #{result.status.state}"
+when A2A::Message then puts result.parts.first.text
+end
+```
+
+## What's included
+
+### Client
+
+`A2A::Client` covers all eleven A2A JSON-RPC methods:
+
+| Method | Client call |
+|--------|-------------|
+| `SendMessage` | `client.send_message(message, configuration:, metadata:, tenant:)` |
+| `SendStreamingMessage` | `client.send_streaming_message(message, ...) { \|event\| }` |
+| `GetTask` | `client.get_task(id, history_length:)` |
+| `ListTasks` | `client.list_tasks(page_size:, page_token:, status:, ...)` |
+| `CancelTask` | `client.cancel_task(id_or_task)` |
+| `SubscribeToTask` | `client.subscribe_to_task(id) { \|event\| }` |
+| `CreatePushNotificationConfig` | `client.create_task_push_notification_config(config)` |
+| `GetPushNotificationConfig` | `client.get_task_push_notification_config(task_id:, id:)` |
+| `ListPushNotificationConfigs` | `client.list_task_push_notification_configs(task_id:)` |
+| `DeletePushNotificationConfig` | `client.delete_task_push_notification_config(task_id:, id:)` |
+| `GetExtendedAgentCard` | `client.get_extended_agent_card` |
+
+The client accepts both a `Task` object and a plain string ID for operations
+that reference tasks. Passing a terminal `Task` to `cancel_task` raises
+`TaskNotCancelableError` locally without a network round-trip.
+
+### Protocol bindings
+
+```ruby
+# JSON-RPC 2.0
+protocol = A2A::Protocol::JsonRpc.new(
+  url: "https://agent.example.com/rpc",
+  headers: { "Authorization" => "Bearer token" }
+)
+
+# HTTP+JSON (REST-style)
+protocol = A2A::Protocol::HttpJson.new(
+  url: "https://agent.example.com",
+  extensions: ["https://ext.example.com/v1"]
+)
+
+client = A2A::Client.new(protocol: protocol)
+```
+
+### Data model
+
+All message types implement `.from_h(hash)` / `#to_h` for lossless
+round-trip serialisation against the A2A wire format.
+
+| Class | Purpose |
+|-------|---------|
+| `Task` | Unit of work; carries `id`, `status`, `artifacts`, `history` |
+| `Task::Status` | State + optional message + timestamp |
+| `Task::State` | String constants + `TERMINAL` / `RESUMABLE` collections |
+| `Message` | User↔agent communication unit; carries `parts` |
+| `Artifact` | Task output (not for communication) |
+| `Part::Text` | Plain text content |
+| `Part::Data` | Structured JSON content |
+| `Part::File` | File by URL or base64 inline (`raw`/`url`, `filename`, `media_type`) |
+| `Role` | `ROLE_USER` / `ROLE_AGENT` constants |
+
+### Streaming
+
+```ruby
+client.send_streaming_message(message) do |event|
+  case event.type
+  when :status_update   then puts event.payload.status.state
+  when :artifact_update then print event.payload.artifact.parts.first.text
+  when :task            then puts "snapshot: #{event.payload.status.state}"
+  when :message         then puts event.payload.parts.first.text
+  end
+end
+```
+
+Streaming stops automatically when a terminal state is detected. Without a
+block, `send_streaming_message` returns a `Streaming::Subscription` that is
+`Enumerable`.
+
+### Server-side primitives
+
+The gem includes three classes for building server handlers:
+
+| Class | Purpose |
+|-------|---------|
+| `JSONRPCEnvelope` | Build success/error response envelopes; parse incoming request envelopes |
+| `Operation::SendMessageRequest` | Deserialise incoming `SendMessage`/`SendStreamingMessage` params |
+| `Streaming::SSEWriter` | Format `Streaming::Response` objects as SSE frames |
+
+```ruby
+# Parse an incoming request
+id, method, params = A2A::JSONRPCEnvelope.parse_request(raw_hash)
+req = A2A::Operation::SendMessageRequest.from_h(params)
+
+# Build a response
+A2A::JSONRPCEnvelope.success(id: id, result: { "task" => task.to_h })
+
+# Write an SSE frame
+A2A::Streaming::SSEWriter.encode(streaming_response, id: id)
+```
+
+### Task transitions (server-side)
+
+`Task#transition_to` returns a new immutable `Task` — the original is never
+mutated. Raises `TaskNotCancelableError` if the task is already terminal.
+
+```ruby
+task = task.transition_to(A2A::Task::State::WORKING)
+task = task.transition_to(A2A::Task::State::COMPLETED, timestamp: Time.now.utc.iso8601)
+```
+
+### AgentCard builder
+
+```ruby
+card = A2A::AgentCard::Builder.new
+  .name("My Agent")
+  .description("Does useful things.")
+  .version("1.0")
+  .interface(url: "https://agent.example.com/rpc",
+             protocol_binding: A2A::AgentInterface::JSONRPC,
+             protocol_version: "1.0")
+  .capabilities(streaming: true, push_notifications: true)
+  .input_modes("text/plain")
+  .output_modes("text/plain")
+  .skill(id: "summarise", name: "Summarise",
+         description: "Summarises documents", tags: ["text"])
+  .build
+```
+
+### Push notifications
+
+```ruby
+# Dispatch from a server
+dispatcher = A2A::PushNotification::Dispatcher.new
+dispatcher.dispatch(config, streaming_response)
+
+# Receive in a Rack app
+use A2A::PushNotification::Receiver,
+    path: "/a2a/webhook",
+    credentials: ENV["WEBHOOK_TOKEN"] do |event|
+  MyJob.perform_later(event.to_h.to_json)
+end
+```
+
+### Security schemes
+
+All five A2A security scheme types are modelled: `HTTPAuth`, `APIKey`,
+`OAuth2` (authorization code, client credentials, device code),
+`OpenIDConnect`, and `MutualTLS`. `SecurityScheme.from_h` dispatches on
+the discriminator key.
+
+### Errors
+
+All errors inherit from `A2A::Error` and carry a `code` integer matching
+the A2A spec's JSON-RPC error codes. `A2A.from_json_rpc_error(hash)` builds
+the correct subclass from a raw error hash.
+
+```
+A2A::Error
+├── A2A::TransportError
+├── A2A::AuthenticationError          # HTTP 401
+├── A2A::AuthorizationError           # HTTP 403
+├── A2A::TaskNotFoundError            # -32001
+├── A2A::TaskNotCancelableError       # -32002
+├── A2A::PushNotificationNotSupportedError  # -32003
+├── A2A::UnsupportedOperationError    # -32004
+├── A2A::ContentTypeNotSupportedError # -32005
+├── A2A::VersionNotSupportedError     # -32009
+└── ... (full list in lib/a2a.rb)
+```
+
+## Examples
+
+The [`examples/`](examples/) folder contains worked examples for each area of
+the gem:
+
+| File | Topic |
+|------|-------|
+| [`01_discovery.md`](examples/01_discovery.md) | Fetch an agent card; build a client from it |
+| [`02_send_message.md`](examples/02_send_message.md) | Send text, file, and data messages; configuration; error handling |
+| [`03_streaming.md`](examples/03_streaming.md) | Receive and emit SSE streams; `SSEWriter` |
+| [`04_task_lifecycle.md`](examples/04_task_lifecycle.md) | Fetch, list, cancel, and transition tasks |
+| [`05_push_notifications.md`](examples/05_push_notifications.md) | Register configs; dispatch and receive push events |
+| [`06_agent_card.md`](examples/06_agent_card.md) | Declare and serve an `AgentCard` |
+| [`07_server_side.md`](examples/07_server_side.md) | Parse requests; build responses; stream SSE from a Rack handler |
+| [`08_security_schemes.md`](examples/08_security_schemes.md) | All five security scheme types; attach to a card |
+
+## Development
+
+```bash
+bin/setup        # install dependencies
+bin/console      # open a pry REPL with A2A loaded
+bundle exec rake # run the test suite
+bin/install-hooks # install the commit-msg hook (conventional commits)
+```
+
+## Releasing a new version
+
+Commits must follow [Conventional Commits](https://www.conventionalcommits.org/).
+Install the local commit-msg hook once after cloning:
+
+```bash
+bin/install-hooks
+```
+
+Valid types: `feat` (Added), `fix` (Fixed), `refactor`/`chore` (Changed),
+`perf`, `revert`/`remove`, `deprecate`, `security`. Other types land in Other.
+Merge commits and `Release vX.Y.Z` commits are exempt.
+
+### Run the release script
+
+```bash
+bin/release patch   # 0.1.0 → 0.1.1
+bin/release minor   # 0.1.0 → 0.2.0
+bin/release major   # 0.1.0 → 1.0.0
+```
+
+The script will:
+
+1. Abort if the working tree has uncommitted changes
+2. Run the full test suite (`bundle exec rake spec`)
+3. Parse `git log` since the previous tag and group commits by type
+4. Show you the draft changelog entry and the new version, then ask for confirmation
+5. Write the changelog entry into `CHANGELOG.md`
+6. Bump `lib/a2a/version.rb`
+7. Commit both files with the message `Release vx.y.z`
+8. Create an annotated git tag `vx.y.z`
+
+Aborts if no conventional commits are found since the last tag.
+
+### 3. Push and publish
+
+```bash
+git push origin main vx.y.z     # push the commit and the tag together
+
+bundle exec rake build           # builds pkg/a2a-rb-x.y.z.gem
+gem push pkg/a2a-rb-x.y.z.gem   # publish to RubyGems (requires credentials)
+```
+
+> RubyGems MFA is enforced for this gem. You will be prompted for a one-time
+> password when running `gem push`.
+
+### Preflight check (optional)
+
+```bash
+bundle exec rake preflight
+```
+
+Runs specs, checks that `[Unreleased]` is not empty, and verifies the working
+tree is clean.
+
+---
+
+### Quick reference
+
+| Command | What it does |
+|---------|--------------|
+| `bin/release patch` | Bump patch, update changelog, commit, tag |
+| `bin/release minor` | Bump minor, update changelog, commit, tag |
+| `bin/release major` | Bump major, update changelog, commit, tag |
+| `bundle exec rake preflight` | Specs + changelog check + clean tree |
+| `bundle exec rake build` | Build `.gem` into `pkg/` |
+| `gem push pkg/a2a-rb-x.y.z.gem` | Publish to RubyGems |
+| `bundle exec rake spec` | Run tests only |

data/lib/a2a/agent_capabilities.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentCapabilities
+    attr_reader :streaming, :push_notifications, :extensions, :extended_agent_card
+
+    def initialize(streaming: nil, push_notifications: nil, extensions: nil, extended_agent_card: nil)
+      @streaming = streaming
+      @push_notifications = push_notifications
+      @extensions = extensions
+      @extended_agent_card = extended_agent_card
+    end
+
+    def self.from_h(hash)
+      new(
+        streaming: hash["streaming"],
+        push_notifications: hash["pushNotifications"],
+        extensions: hash["extensions"]&.map { AgentExtension.from_h(_1) },
+        extended_agent_card: hash["extendedAgentCard"]
+      )
+    end
+
+    def to_h
+      {
+        "streaming" => streaming,
+        "pushNotifications" => push_notifications,
+        "extensions" => extensions,
+        "extendedAgentCard" => extended_agent_card
+      }.compact
+    end
+  end
+end

data/lib/a2a/agent_card/builder.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentCard
+    # Fluent builder for constructing an AgentCard without deep nested constructors.
+    #
+    # Usage:
+    #   card = A2A::AgentCard::Builder.new
+    #     .name("My Agent")
+    #     .description("Does things")
+    #     .version("1.0")
+    #     .interface(url: "https://agent.example.com/rpc", protocol_binding: A2A::AgentInterface::JSONRPC)
+    #     .capabilities(streaming: true)
+    #     .input_modes("text/plain")
+    #     .output_modes("text/plain")
+    #     .skill(id: "summarise", name: "Summarise", description: "Summarises text", tags: ["text"])
+    #     .build
+    class Builder
+      def initialize
+        @name = nil
+        @description = nil
+        @version = nil
+        @interfaces = []
+        @capabilities_opts = {}
+        @input_modes = []
+        @output_modes = []
+        @skills = []
+        @provider = nil
+        @documentation_url = nil
+        @icon_url = nil
+        @security_schemes = {}
+        @security_requirements = nil
+      end
+
+      def name(value)
+        @name = value
+        self
+      end
+
+      def description(value)
+        @description = value
+        self
+      end
+
+      def version(value)
+        @version = value
+        self
+      end
+
+      # Appends a supported interface. Accepts either an AgentInterface object
+      # or kwargs forwarded to AgentInterface.new.
+      def interface(iface = nil, **kwargs)
+        @interfaces << (iface.is_a?(AgentInterface) ? iface : AgentInterface.new(**kwargs))
+        self
+      end
+
+      # Sets capabilities via kwargs (streaming:, push_notifications:, etc.)
+      # or accepts an AgentCapabilities object directly.
+      def capabilities(caps = nil, **kwargs)
+        @capabilities_opts = caps.is_a?(AgentCapabilities) ? caps : kwargs
+        self
+      end
+
+      # Appends one or more accepted input MIME types.
+      def input_modes(*modes)
+        @input_modes.concat(modes.flatten)
+        self
+      end
+
+      # Appends one or more accepted output MIME types.
+      def output_modes(*modes)
+        @output_modes.concat(modes.flatten)
+        self
+      end
+
+      # Appends a skill. Accepts either an AgentSkill object or kwargs
+      # forwarded to AgentSkill.new.
+      def skill(obj = nil, **kwargs)
+        @skills << (obj.is_a?(AgentSkill) ? obj : AgentSkill.new(**kwargs))
+        self
+      end
+
+      def provider(org, url: nil)
+        @provider = AgentProvider.new(organization: org, url: url)
+        self
+      end
+
+      def documentation_url(value)
+        @documentation_url = value
+        self
+      end
+
+      def icon_url(value)
+        @icon_url = value
+        self
+      end
+
+      # Registers a security scheme under `name`. Accepts a SecurityScheme
+      # subclass or a raw hash forwarded to SecurityScheme.from_h.
+      def security_scheme(name, scheme)
+        @security_schemes[name] = scheme.is_a?(Hash) ? SecurityScheme.from_h(scheme) : scheme
+        self
+      end
+
+      def security(requirements)
+        @security_requirements = requirements
+        self
+      end
+
+      def build
+        AgentCard.new(
+          name: @name,
+          description: @description,
+          version: @version,
+          supported_interfaces: @interfaces,
+          capabilities: resolve_capabilities,
+          default_input_modes: @input_modes,
+          default_output_modes: @output_modes,
+          skills: @skills,
+          provider: @provider,
+          documentation_url: @documentation_url,
+          icon_url: @icon_url,
+          security_schemes: @security_schemes.empty? ? nil : @security_schemes,
+          security_requirements: @security_requirements
+        )
+      end
+
+      private
+
+      def resolve_capabilities
+        @capabilities_opts.is_a?(AgentCapabilities) ? @capabilities_opts : AgentCapabilities.new(**@capabilities_opts)
+      end
+    end
+  end
+end

data/lib/a2a/agent_card/signature.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentCard
+    # §8.4.2 — JWS signature attached to an AgentCard.
+    # `protected` is the base64url-encoded JWS Protected Header.
+    # `signature` is the base64url-encoded signature value.
+    # `header` is the optional JWS Unprotected Header (plain JSON object, not encoded).
+    class Signature
+      attr_reader :protected_header, :signature, :header
+
+      def initialize(protected_header:, signature:, header: nil)
+        @protected_header = protected_header
+        @signature = signature
+        @header = header
+      end
+
+      def self.from_h(hash)
+        new(
+          protected_header: hash.fetch("protected"),
+          signature: hash.fetch("signature"),
+          header: hash["header"]
+        )
+      end
+
+      def to_h
+        {
+          "protected" => protected_header,
+          "signature" => signature,
+          "header" => header
+        }.compact
+      end
+    end
+  end
+end

data/lib/a2a/agent_card/verifier.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module A2A
+  class AgentCard
+    # §8.4.3 — Verifies AgentCard signatures.
+    # Signing is optional; unsigned cards are considered valid.
+    # Full JWS verification (RFC 7515 + RFC 8785 canonicalisation) is not yet
+    # implemented. See §8.4 of the A2A spec for the required algorithm.
+    class Verifier
+      def self.verify!(card)
+        return true if card.signatures.nil? || card.signatures.empty?
+
+        raise NotImplementedError,
+              "AgentCard signature verification is not yet implemented (§8.4). " \
+              "The card carries #{card.signatures.length} signature(s) but they cannot be verified."
+      end
+    end
+  end
+end