a2a-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b32fb9c3818579632e24051395d8f6e7820cde362a7068d861d0ee281b4a6c9
+  data.tar.gz: 1bbe7422de7f70a8e6c01e50f15b7d07a7232682fbac9c81276c8bd69867a6cf
+SHA512:
+  metadata.gz: a3c1f685fa38fb4b44f8329d7c0fea22a3ce3c5503e3904b4632e2cb933df2a904091021c530bcc78e24ddc015f392bf73dcfb94a4deded9fdb6343c18a353c4
+  data.tar.gz: 163d991b30b75f3096270fffe6f74e9fb5ba5744df8897aea595c55ccf516e278ef159385c1ea79f244a646350eb67ec0e05c4498d66e51ea42f1d9a61790747

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# 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 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-06
+
+### Added
+
+- Rails-native A2A v1.0 server integration backed by `agent2agent ~> 2.0.0`.
+- `A2A::Rails::Agent` and Skill DSL with application-owned Handler dispatch.
+- Single-Skill automatic dispatch and multi-Skill Router support.
+- Agent Card generation at `GET /.well-known/agent-card.json`.
+- A2A JSON-RPC endpoint at `POST /a2a`.
+- Synchronous Task lifecycle with `SUBMITTED`, `WORKING`, `COMPLETED`, `FAILED`, `REJECTED`, and `CANCELED` states.
+- String, Hash, Array, and nil Handler-result mapping to A2A Artifacts.
+- Thread-safe process-local in-memory Task Store.
+- `SendMessage`, `GetTask`, `ListTasks`, and `CancelTask` support.
+- `ListTasks` filtering, stable newest-first ordering, and opaque snapshot pagination.
+- Lazy Rails configuration and Agent resolution.
+- Automatically mounted Rails Engine and thin API controllers.
+- Rails-facing logging boundary that suppresses the upstream SDK Rack-environment INFO log.
+- `a2a:rails:install` and `a2a:rails:agent NAME` generators.
+- Generator-backed Echo Quick Start verified through a real packaged `.gem` installed into a clean Rails application.
+- CI coverage for Ruby 3.3, 3.4, and 4.0 with Rails 8.0 and 8.1.
+
+### Compatibility
+
+- Ruby `>= 3.3`.
+- Rails `>= 8.0, < 8.2`.
+- A2A protocol version `1.0`.
+- `agent2agent ~> 2.0.0`.
+
+### Known limitations
+
+- Server-only; no A2A client.
+- Non-streaming synchronous execution only.
+- No Push Notifications, gRPC, ActiveJob execution, or durable Task Store.
+- Default Task Store is process-local and is not shared across processes or preserved across restarts.
+- Handler cancellation does not interrupt already-running application code or undo business side effects.
+- `INPUT_REQUIRED` and `AUTH_REQUIRED` flows are not implemented.
+- Continuing an existing Task via `message.taskId` is not supported in v0.1.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 changquan.cui
+
+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,499 @@
+# a2a-rails
+
+Rails-native integration for exposing Rails applications as A2A agents.
+
+> **Status: the v0.1.0 release candidate is prepared and CI-verified; the actual public release is next.**
+
+## Current Status
+
+The A2A v1.0 SDK integration path, Gem core, Protocol Adapter, Agent / Skill DSL, Task lifecycle, Configuration, Agent Card generation, Rails Engine HTTP endpoints, generators, source-tree Quick Start, packaged-gem installation path, and v0.1.0 release-candidate metadata are now verified.
+
+**Current stage:** Step 15-13 completed — v0.1.0 release-candidate preparation
+
+**Next step:** **Step 15-14 — Execute the v0.1.0 release: final artifact verification from the exact main commit, public-release readiness, `v0.1.0` tag, RubyGems publication, GitHub Release, and post-release smoke verification.**
+
+Step 15-13 adds `CHANGELOG.md`, canonical v0.1.0 release notes, a pre-release / publish / post-release checklist, and final RubyGems metadata for source, changelog, documentation, issue tracker, and MFA. The packaged-gem smoke now verifies those metadata fields plus README, CHANGELOG, LICENSE, Ruby compatibility, generator discovery, clean-app installation, Agent Card retrieval, and Echo `SendMessage`. The release-candidate CI is **13 / 13 green**, while the Gem suite remains **70 tests / 240 assertions / 0 failures / 0 errors / 0 skips**. See [Draft PR #7](https://github.com/cuichangquan/a2a-rails/pull/7).
+
+Step 15-12 verified the actual built gem in a clean Rails application. Step 15-11 added the intentionally small `install` / `agent` generators and the generator-backed source-tree Quick Start. Step 15-10 implemented the automatically mounted Rails Engine, thin API controllers, a process-local Runtime that shares the in-memory Task Store across HTTP requests, and the Rails-facing SDK logging boundary. Step 15-9 implemented lazy Configuration and Agent Card generation. Step 15-8 wired `SendMessage`, `GetTask`, `ListTasks`, and `CancelTask` through the real SDK. Step 15-7 implemented the SDK-independent Task core. Step 15-6 implemented the Rails-facing Agent / Skill / Dispatcher API. Step 15-5 introduced the loadable Gem skeleton and Protocol Adapter. Step 15-4 verified the `agent2agent 2.0.0` SDK path across the supported Ruby / Rails matrix.
+
+## Development Progress
+
+- [x] 1. Research A2A Protocol v1.0
+- [x] 2. Research Ruby A2A SDKs / Gems
+- [x] 3. Research Rails-oriented A2A alternatives
+- [x] 4. Define the problem a2a-rails solves
+- [x] 5. Define v0.1 scope
+- [x] 6. Define terminology
+- [x] 7. Define architecture
+- [x] 8. Define Ruby SDK boundary
+- [x] 9. Public API Design
+- [x] 10. Agent Card Design
+- [x] 11. Task Lifecycle Design
+- [x] 12. Test Strategy
+- [x] 13. Gem Structure
+- [x] 14. Quick Start Design
+- [ ] **15. Implementation / release preparation ← IN PROGRESS**
+  - [x] 15-4 SDK compatibility spike
+  - [x] 15-5 Gem skeleton + Protocol Adapter
+  - [x] 15-6 Agent / Skill DSL + Dispatcher
+  - [x] 15-7 Task core + MemoryStore
+  - [x] 15-8 Task operations through real SDK
+  - [x] 15-9 Configuration + Agent Card
+  - [x] 15-10 Rails Engine HTTP integration
+  - [x] 15-11 Generators + generated Quick Start
+  - [x] 15-12 Packaged-gem / release-readiness verification
+  - [x] 15-13 v0.1.0 release-candidate preparation
+  - [ ] 15-14 v0.1.0 release execution
+
+## v0.1 Direction
+
+v0.1 is **server-first** and focuses on exposing a Rails application as an A2A Agent.
+
+```text
+A2A Protocol
+     ↓
+Ruby A2A SDK
+     ↓
+a2a-rails
+     ↓
+Rails Application
+     ↓
+Business Logic
+```
+
+Main principles:
+
+- Do not reimplement the A2A Protocol.
+- Focus on Rails integration.
+- Keep SDK-specific APIs out of the public API.
+- Prefer a small, non-streaming server scope for v0.1.
+- Keep a2a-rails independent from ActingFor.
+
+## Quick Start
+
+> The flow below is runtime-verified both from the repository source tree and from the built `a2a-rails-0.1.0` gem installed into a clean Rails application.
+
+### 1. Add and install
+
+```bash
+bundle add a2a-rails
+bin/rails generate a2a:rails:install
+bin/rails generate a2a:rails:agent echo
+mkdir -p app/services/echo
+```
+
+`install` creates only:
+
+```text
+config/initializers/a2a_rails.rb
+```
+
+with:
+
+```ruby
+A2A::Rails.configure do |config|
+  config.agent = "YourAgent"
+  config.public_base_url = ENV["A2A_PUBLIC_BASE_URL"]
+end
+```
+
+`agent echo` creates only:
+
+```text
+app/agents/echo_agent.rb
+```
+
+with:
+
+```ruby
+class EchoAgent < A2A::Rails::Agent
+  name "Echo Agent"
+  description "TODO"
+  version "1.0"
+
+  # Add at least one skill.
+end
+```
+
+The generator deliberately does **not** create a Handler, route, controller, Task Store, job, migration, or registration side effect. It also does not reference a Handler that does not exist yet.
+
+### 2. Create the Handler
+
+Create `app/services/echo/reply.rb`:
+
+```ruby
+class Echo::Reply
+  def self.call(message:, context:)
+    text = message[:parts]
+      .filter_map { |part| part[:text] }
+      .join("\n")
+
+    "Echo: #{text}"
+  end
+end
+```
+
+### 3. Define the Skill
+
+Replace `app/agents/echo_agent.rb` with:
+
+```ruby
+class EchoAgent < A2A::Rails::Agent
+  name "Echo Agent"
+  description "Echo messages"
+  version "1.0"
+
+  skill :reply,
+    description: "Echo a message",
+    tags: %w[echo],
+    handler: Echo::Reply
+end
+```
+
+A single Skill is selected automatically. No Router is required.
+
+### 4. Register the Agent
+
+Replace `config/initializers/a2a_rails.rb` with:
+
+```ruby
+A2A::Rails.configure do |config|
+  config.agent = "EchoAgent"
+  config.public_base_url = ENV["A2A_PUBLIC_BASE_URL"]
+end
+```
+
+For localhost, leave `A2A_PUBLIC_BASE_URL` unset or set it to `http://localhost:3000`. The Agent class name remains a String until an A2A endpoint resolves it, preserving Rails autoload / reload behavior.
+
+No explicit Engine mount or host `config/routes.rb` change is required.
+
+### 5. Check the Agent Card
+
+```bash
+bin/rails server
+```
+
+```bash
+curl -sS http://localhost:3000/.well-known/agent-card.json \
+  -H "A2A-Version: 1.0"
+```
+
+Expected essentials:
+
+- HTTP 200
+- Agent name `Echo Agent`
+- Skill ID `reply`
+- JSON-RPC A2A interface pointing to `http://localhost:3000/a2a`
+
+### 6. Send the first message
+
+```bash
+curl -sS -X POST http://localhost:3000/a2a \
+  -H "Content-Type: application/json" \
+  -H "A2A-Version: 1.0" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "SendMessage",
+    "params": {
+      "message": {
+        "messageId": "msg-1",
+        "role": "ROLE_USER",
+        "parts": [{"text": "Hello"}]
+      }
+    }
+  }'
+```
+
+Success means:
+
+```text
+result.task.status.state == TASK_STATE_COMPLETED
+Artifact Text Part == "Echo: Hello"
+```
+
+See [the complete Quick Start design and verification notes](docs/design/quick-start.md).
+
+## Target Developer Experience
+
+```ruby
+class ShoppingAgent < A2A::Rails::Agent
+  name "Shopping Agent"
+  description "Search and purchase products"
+  version "1.0"
+
+  skill :search_products,
+    description: "Search products",
+    tags: %w[shopping search],
+    handler: Shopping::SearchProducts
+end
+```
+
+Handler:
+
+```ruby
+class Shopping::SearchProducts
+  def self.call(message:, context:)
+    # Rails business logic
+  end
+end
+```
+
+Registration:
+
+```ruby
+A2A::Rails.configure do |config|
+  config.agent = "ShoppingAgent"
+  config.public_base_url = ENV["A2A_PUBLIC_BASE_URL"]
+end
+```
+
+v0.1 targets **one public A2A Agent per Rails application**. Handlers receive SDK-independent Ruby Hashes for `message` and `context`.
+
+For multiple Skills, the application supplies a Router. The Router receives `skills:` as a frozen `Array<Symbol>` of declared Skill IDs and may return a matching Symbol or String. Unknown selections raise `A2A::Rails::UnknownSkillError`; the Dispatcher never silently chooses the first Skill.
+
+## Agent Card
+
+The Gem automatically exposes:
+
+```text
+GET  /.well-known/agent-card.json
+POST /a2a
+```
+
+Agent Card behavior:
+
+- generated from the Agent / Skill DSL;
+- Skill IDs and default display names are generated from Skill declarations;
+- optional `examples`, `input_modes`, and `output_modes` map to A2A Agent Card fields;
+- Handler internals are never exposed;
+- `public_base_url` wins when configured, otherwise the request base URL is used;
+- default input/output mode is `text/plain`;
+- Streaming, Push Notifications, and Extended Agent Cards are disabled for v0.1;
+- generated Cards pass the real `agent2agent 2.0.0` Agent Card schema.
+
+## Task Lifecycle
+
+Internally the Gem keeps SDK-independent Task states:
+
+```text
+SUBMITTED
+    ↓
+WORKING
+    ├──→ COMPLETED
+    ├──→ FAILED
+    └──→ REJECTED
+```
+
+Cancellation can move a non-terminal Task to `CANCELED`.
+
+Handler result mapping:
+
+```text
+normal return                  → COMPLETED
+A2A::Rails::RejectedTask       → REJECTED
+unexpected exception           → FAILED
+```
+
+Artifact mapping:
+
+```text
+String       → Text Part
+Hash / Array → Data Part
+nil          → no Artifact
+other object → ArtifactMappingError
+```
+
+v0.1 Task behavior:
+
+- server-generated Task IDs;
+- client Context ID preserved, otherwise server-generated;
+- terminal states are immutable;
+- thread-safe process-local `Task::MemoryStore` by default;
+- `SendMessage`, `GetTask`, `ListTasks`, and `CancelTask` supported;
+- `ListTasks` supports context/state/timestamp filters, stable newest-first ordering, page sizes 1–100, and opaque snapshot pagination;
+- cancellation is atomic, but does not interrupt Handler execution or undo business side effects;
+- v0.1 Handler execution accepts text Message Parts;
+- continuing an existing Task via `message.taskId` is not supported;
+- `INPUT_REQUIRED` and `AUTH_REQUIRED` are out of scope.
+
+The default store is for development and simple synchronous workloads. Tasks and pagination cursors are process-local and are not durable across process restarts or shared between processes.
+
+## Rails Integration
+
+Step 15-10 provides:
+
+- an automatically mounted Rails Engine;
+- thin `ActionController::API` controllers;
+- `/.well-known/agent-card.json` and `/a2a` routes;
+- lazy application Agent resolution;
+- one process-local Runtime that shares the default Task Store across HTTP requests;
+- request-derived Agent Card URL fallback;
+- a logging boundary that suppresses the upstream SDK `A2A::Server::Triage` INFO log containing the full Rack environment while restoring prior Console logging state afterward.
+
+## Generators
+
+Step 15-11 implements:
+
+```text
+a2a:rails:install
+a2a:rails:agent NAME
+```
+
+Verified contract:
+
+- `install` creates only `config/initializers/a2a_rails.rb`;
+- `agent echo` creates only `app/agents/echo_agent.rb`;
+- the Agent scaffold has no dangling Handler reference;
+- the generated Agent is not automatically registered;
+- namespace-based generator invocation reproduces the documented files;
+- the generated Echo setup boots under Rails and completes a real A2A `SendMessage` request.
+
+Step 15-12 verifies the same generator contract from the **built and installed gem**, in a clean Rails application outside the repository source checkout.
+
+## Packaged Gem Verification
+
+Step 15-12 verifies the distribution artifact itself:
+
+- `gem build a2a-rails.gemspec` produces `a2a-rails-0.1.0`;
+- the package contains the Engine, generator classes, generator templates, and routes required at runtime;
+- the clean app resolves `a2a-rails-0.1.0` from the installed RubyGems path, not from the repository checkout;
+- actual `bin/rails generate` commands discover both generators;
+- generated files match the documented scaffold contract;
+- the clean app boots and serves the generated Agent Card;
+- `SendMessage` completes with the Echo Artifact;
+- Step 15-12 verified package SHA256: `09c55122c5d5e6cb5f9b735664d70b000f67d23dcaad9f4a8ff960dbe02dd410`.
+
+Step 15-13 extends this verification to user-facing release files and RubyGems metadata. The final published artifact must still be rebuilt and hashed from the exact tagged release commit.
+
+## Release Candidate
+
+Step 15-13 prepares, but does not publish, v0.1.0:
+
+- [CHANGELOG](CHANGELOG.md)
+- [v0.1.0 release notes](docs/release/v0.1.0.md)
+- [v0.1.0 release checklist](docs/release/v0.1.0-checklist.md)
+
+The gemspec publishes canonical links for source code, changelog, documentation, and issue tracking, and requires RubyGems MFA. `README.md`, `CHANGELOG.md`, and `LICENSE` are verified as package contents.
+
+No `v0.1.0` tag, RubyGems publication, GitHub Release, or repository-visibility change is performed in Step 15-13.
+
+## Test Strategy
+
+v0.1 uses **Minitest** with four layers:
+
+```text
+4. Protocol E2E / Smoke Tests
+3. Rails Integration Tests
+2. Adapter Contract Tests
+1. Core Unit Tests
+```
+
+The current CI matrix covers:
+
+- Gem: Ruby 3.3 / 3.4 / 4.0
+- SDK spike: Ruby 3.3 / 3.4 / 4.0
+- Rails: Ruby 3.3 / 3.4 / 4.0 × Rails 8.0 / 8.1
+- Packaged gem: Ruby 3.4 + clean Rails 8.1 application
+
+Current Step 15-13 result:
+
+```text
+13 / 13 CI jobs green
+70 tests
+240 assertions
+0 failures
+0 errors
+0 skips
+```
+
+Known warning-enabled output from upstream `agent2agent 2.0.0` remains, including circular-require / indentation / URI-parser warnings. Those warnings are distinct from the Rack-environment INFO logging that a2a-rails suppresses at the Rails-facing adapter boundary.
+
+## Gem Structure
+
+```text
+lib/a2a/rails/
+├── agent.rb
+├── skill.rb
+├── dispatcher.rb
+├── configuration.rb
+├── runtime.rb
+├── engine.rb
+├── agent_card/
+├── task/
+└── protocol/
+
+lib/generators/a2a/rails/
+├── install_generator.rb
+├── agent_generator.rb
+└── templates/
+```
+
+Key boundaries:
+
+- Rails Engine / controllers / routes are only the Rails integration layer.
+- SDK-specific behavior stays behind `Protocol::Adapter` / `Protocol::Agent2AgentAdapter`.
+- A2A camelCase fields, `TASK_STATE_*`, SDK schema objects, and SDK errors stay in the Protocol layer.
+- Agent / Handler application constants remain lazily resolved through Rails.
+- ActiveRecord and ActiveJob are not runtime requirements.
+- v0.1 targets Ruby `>= 3.3` and Rails `>= 8.0, < 8.2`.
+
+Current main dependencies:
+
+- `agent2agent ~> 2.0.0`
+- `actionpack >= 8.0, < 8.2`
+- `json < 3`
+- `rack >= 3.0, < 4`
+- `railties >= 8.0, < 8.2`
+
+## v0.1 Scope
+
+Included:
+
+- Rails integration
+- `A2A::Rails::Agent`
+- Skill DSL and Handler dispatch
+- Agent Card generation
+- `/.well-known/agent-card.json`
+- `POST /a2a`
+- Task lifecycle
+- `GetTask`, `ListTasks`, `CancelTask`
+- `A2A-Version: 1.0` validation
+- in-memory Task Store
+- Rails Engine / Routes
+- Configuration
+- `install` / `agent` generators
+- Rails logging boundary
+- test support
+
+Not included in v0.1:
+
+- A2A Client
+- ActiveRecord Task Store
+- ActiveJob Task execution
+- SSE / BiDi Streaming
+- Push Notifications
+- gRPC
+- Human-in-the-loop
+- `INPUT_REQUIRED` / `AUTH_REQUIRED` flows
+- Agent Registry / Marketplace
+- OAuth Server
+- Authorization Engine
+- ActingFor integration
+- Admin UI
+- LLM Agent Framework
+- Orchestration Framework
+
+## Design Documents
+
+- [v0.1 Design Decisions](docs/design/v0.1-decisions.md)
+- [v0.1 Test Strategy](docs/design/test-strategy.md)
+- [v0.1 Gem Structure](docs/design/gem-structure.md)
+- [v0.1 Quick Start Design](docs/design/quick-start.md)
+- [Step 15 SDK compatibility findings](docs/design/sdk-compatibility-spike.md)
+
+## Release Documents
+
+- [CHANGELOG](CHANGELOG.md)
+- [v0.1.0 Release Notes](docs/release/v0.1.0.md)
+- [v0.1.0 Release Checklist](docs/release/v0.1.0-checklist.md)

data/app/controllers/a2a/rails/agent_cards_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class AgentCardsController < ApplicationController
+      def show
+        response.set_header("A2A-Version", Protocol::Agent2AgentAdapter::PROTOCOL_VERSION)
+        render json: A2A::Rails.runtime.agent_card(request_base_url: request.base_url)
+      end
+    end
+  end
+end

data/app/controllers/a2a/rails/application_controller.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class ApplicationController < ActionController::API
+    end
+  end
+end

data/app/controllers/a2a/rails/requests_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module A2A
+  module Rails
+    class RequestsController < ApplicationController
+      def create
+        status, headers, body = A2A::Rails.runtime.call(
+          env: request.env,
+          request_base_url: request.base_url
+        )
+
+        self.status = status
+        headers.each { |name, value| response.set_header(name, value) }
+        self.response_body = body
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+A2A::Rails::Engine.routes.draw do
+  get "/.well-known/agent-card.json", to: "agent_cards#show", defaults: { format: :json }
+  post "/a2a", to: "requests#create"
+end