simple_a2a 0.1.0

data/docs/examples/streaming.md

@@ -0,0 +1,81 @@
+# Streaming Demo
+
+`examples/02_streaming` demonstrates `tasks/sendSubscribe` and Server-Sent Events (SSE). The server streams an article word by word, and the client prints chunks as they arrive.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/02_streaming/server.rb` | Defines `StreamingExecutor`, advertises streaming support, and emits status and artifact events |
+| `examples/02_streaming/client.rb` | Uses `A2A.sse_client` and `send_subscribe` to consume streamed events |
+
+## Run it
+
+From the repository root:
+
+```bash
+bundle exec ruby examples/run 02_streaming
+```
+
+Manual run:
+
+```bash
+bundle exec ruby examples/02_streaming/server.rb
+bundle exec ruby examples/02_streaming/client.rb
+```
+
+## Server behavior
+
+The streaming executor starts the task, emits a working status, sends artifact chunks, completes the task, and emits a final status.
+
+```ruby
+def call(ctx)
+  ctx.task.start!
+  ctx.emit_status
+
+  WORDS.each_with_index do |word, i|
+    text = i.zero? ? word : " #{word}"
+
+    artifact = A2A::Models::Artifact.new(
+      index: 0,
+      parts: [A2A::Models::Part.text(text)],
+      append: i > 0,
+      last_chunk: i == WORDS.length - 1
+    )
+
+    ctx.emit_artifact(artifact, append: i > 0, last_chunk: i == WORDS.length - 1)
+  end
+
+  ctx.task.complete!
+  ctx.emit_status(final: true)
+end
+```
+
+The agent card declares streaming support:
+
+```ruby
+A2A::Models::AgentCapabilities.new(streaming: true)
+```
+
+## Client behavior
+
+The client uses `A2A.sse_client` instead of `A2A.client`:
+
+```ruby
+client = A2A.sse_client(url: "http://localhost:9292")
+
+client.send_subscribe(message: A2A::Models::Message.user("stream")) do |event|
+  case event
+  when A2A::Models::TaskStatusUpdateEvent
+    # task state changed
+  when A2A::Models::TaskArtifactUpdateEvent
+    print event.artifact.parts.map(&:text).join
+  end
+end
+```
+
+It also tracks event count, word count, elapsed time, and effective words per minute, which makes it useful for checking end-to-end streaming behavior.
+
+## Relationship to the guide
+
+The [Streaming Responses guide](../guides/streaming.md) explains the API in isolation. This demo shows the same flow as a runnable pair of scripts.

data/docs/getting-started/installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+## Requirements
+
+- Ruby 3.2 or higher (tested on Ruby 4.0)
+- Bundler 2.x
+
+## Gemfile
+
+```ruby
+gem "simple_a2a"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Direct install
+
+```bash
+gem install simple_a2a
+```
+
+## Dependencies
+
+`simple_a2a` pulls in the following gems automatically:
+
+| Gem | Purpose |
+|---|---|
+| `async` | Async fiber runtime |
+| `async-http` | Non-blocking HTTP client (used by `Client::Base` and `Client::SSE`) |
+| `falcon` | Async-native Rack HTTP server |
+| `roda` | Rack router for the server endpoint |
+| `rack` | WSGI-style Ruby web interface |
+| `zeitwerk` | Autoloading |
+| `jwt` | RS256 JWT signing for push notification webhooks |
+| `logger` | Ruby standard logger (bundled gem in Ruby 4.0+) |
+| `simple_flow` | Pipeline composition for executor chains |
+| `typed_bus` | Per-task SSE event fan-out |
+
+## Verifying the install
+
+```ruby
+require "simple_a2a"
+puts A2A::VERSION   # => "0.1.0"
+```

data/docs/getting-started/quick-start.md

@@ -0,0 +1,100 @@
+# Quick Start
+
+This guide walks through building a minimal echo agent and a client that talks to it.
+
+## 1. Create the executor
+
+An **executor** contains your agent's logic. Subclass `A2A::Server::AgentExecutor` and implement `#call`:
+
+```ruby
+require "simple_a2a"
+
+class EchoExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input = ctx.message.text_content
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "reply",
+        parts: [A2A::Models::Part.text("Echo: #{input}")]
+      )
+    ])
+  end
+end
+```
+
+`ctx` is an `A2A::Server::Context` that gives you access to the incoming message, the task object, and helpers for emitting streaming events.
+
+## 2. Build the agent card
+
+The **AgentCard** describes your agent to clients:
+
+```ruby
+card = A2A::Models::AgentCard.new(
+  name:         "EchoAgent",
+  version:      "1.0",
+  capabilities: A2A::Models::AgentCapabilities.new,
+  skills:       [A2A::Models::AgentSkill.new(name: "echo", description: "Echoes your input")],
+  interfaces:   [A2A::Models::AgentInterface.new(
+    type:    "json-rpc",
+    url:     "http://localhost:9292",
+    version: "1.0"
+  )]
+)
+```
+
+## 3. Start the server
+
+```ruby
+server = A2A.server(agent_card: card, executor: EchoExecutor.new)
+server.run   # starts Falcon on localhost:9292
+```
+
+Or with custom host/port:
+
+```ruby
+server = A2A::Server::Base.new(
+  agent_card: card,
+  executor:   EchoExecutor.new,
+  host:       "0.0.0.0",
+  port:       8080
+)
+server.run
+```
+
+## 4. Send a task from a client
+
+In a separate process or script:
+
+```ruby
+require "simple_a2a"
+
+client = A2A.client(url: "http://localhost:9292")
+
+task = client.send_task(message: A2A::Models::Message.user("hello there"))
+puts task.status.state                               # => "completed"
+puts task.artifacts.first.parts.first.text           # => "Echo: hello there"
+```
+
+## 5. Discover the agent card
+
+```ruby
+card = client.agent_card
+puts card.name      # => "EchoAgent"
+puts card.version   # => "1.0"
+```
+
+## 6. List and retrieve tasks
+
+```ruby
+tasks   = client.list_tasks
+task    = client.get_task(tasks.first.id)
+puts task.id
+```
+
+## Next steps
+
+- [Architecture overview](../architecture/index.md) — understand the components
+- [Streaming responses](../guides/streaming.md) — emit incremental SSE events
+- [Runnable examples](../examples/index.md) - run the demo apps in `examples/`
+- [Push notifications](../guides/push-notifications.md) — webhook delivery
+- [API reference](../api/index.md) — full class and method docs

data/docs/guides/custom-storage.md

@@ -0,0 +1,69 @@
+# Custom Storage
+
+The default `Storage::Memory` is ephemeral — tasks are lost on restart. For production, implement `Storage::Base`.
+
+## Interface
+
+```ruby
+class A2A::Storage::Base
+  def save(task)  = raise NotImplementedError
+  def find(id)    = raise NotImplementedError   # nil if missing
+  def find!(id)   = raise NotImplementedError   # raises TaskNotFoundError if missing
+  def delete(id)  = raise NotImplementedError
+  def list        = raise NotImplementedError   # returns Array
+end
+```
+
+## Minimal example
+
+```ruby
+class HashStorage < A2A::Storage::Base
+  def initialize
+    @store = {}
+  end
+
+  def save(task)
+    @store[task.id] = task
+  end
+
+  def find(id)
+    @store[id]
+  end
+
+  def find!(id)
+    @store.fetch(id) { raise A2A::TaskNotFoundError, "Task #{id} not found" }
+  end
+
+  def delete(id)
+    @store.delete(id)
+  end
+
+  def list
+    @store.values
+  end
+end
+```
+
+## Serialization
+
+`A2A::Models::Task` supports round-trip serialization via `to_h` and `from_hash`:
+
+```ruby
+hash = task.to_h                         # => { "id" => "…", "status" => {…}, … }
+task = A2A::Models::Task.from_hash(hash) # => reconstructed Task
+```
+
+Use this for any storage backend that persists JSON (databases, Redis, files):
+
+```ruby
+def save(task)
+  db.set(task.id, task.to_h.to_json)
+  task
+end
+
+def find(id)
+  raw = db.get(id)
+  return nil unless raw
+  A2A::Models::Task.from_hash(JSON.parse(raw))
+end
+```

data/docs/guides/push-notifications.md

@@ -0,0 +1,104 @@
+# Push Notifications
+
+Push notifications let an A2A server deliver task events to a client-registered webhook, rather than requiring the client to maintain an open SSE connection.
+
+## Overview
+
+1. Client registers a webhook URL via `tasks/pushNotification/set`
+2. Server delivers `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` to the URL
+3. Requests are signed with RS256 JWT (optional but recommended)
+
+## Server setup
+
+Create a `PushSender` with an RS256 private key:
+
+```ruby
+require "openssl"
+
+private_key = OpenSSL::PKey::RSA.generate(2048)
+
+push_sender = A2A::Server::PushSender.new(
+  private_key: private_key,
+  key_id:      "my-key-2026",
+  issuer:      "my-agent"
+)
+
+server = A2A::Server::Base.new(
+  agent_card:  card,
+  executor:    MyExecutor.new,
+  push_sender: push_sender
+)
+```
+
+Advertise push notification support in your AgentCard:
+
+```ruby
+capabilities = A2A::Models::AgentCapabilities.new(
+  push_notifications: true
+)
+```
+
+## Delivering events from your executor
+
+Call `push_sender.deliver` with the stored `PushNotificationConfig` and an event:
+
+```ruby
+class MyExecutor < A2A::Server::AgentExecutor
+  def initialize(push_sender:)
+    @push_sender = push_sender
+  end
+
+  def call(ctx)
+    ctx.task.complete!(artifacts: [ … ])
+    event = A2A::Models::TaskStatusUpdateEvent.new(
+      task_id:    ctx.task.id,
+      context_id: ctx.task.context_id,
+      status:     ctx.task.status,
+      final:      true
+    )
+    config = # retrieve PushNotificationConfig registered by the client
+    @push_sender.deliver(config, event)
+  end
+end
+```
+
+`deliver` returns `true` on HTTP 2xx, `false` on failure. Failures are logged via `A2A.logger` but not raised.
+
+## Authentication schemes
+
+### Bearer (RS256 JWT)
+
+A JWT is generated and sent as `Authorization: Bearer <token>`. The token payload includes:
+
+```json
+{
+  "iss": "my-agent",
+  "iat": 1700000000,
+  "exp": 1700000300,
+  "payload_hash": "<SHA-256 hex of the request body>"
+}
+```
+
+```ruby
+auth = A2A::Models::AuthenticationInfo.new(scheme: "bearer")
+```
+
+### Static token
+
+```ruby
+auth = A2A::Models::AuthenticationInfo.new(
+  scheme:      "token",
+  value:       "secret-webhook-token",
+  header_name: "X-Webhook-Token"   # optional, defaults to "Authorization"
+)
+```
+
+Sent as `X-Webhook-Token: Token secret-webhook-token`.
+
+## PushSender without a private key
+
+If no `private_key` is provided, the JWT token is the literal string `"no-key"`. This is useful for local development without RSA setup:
+
+```ruby
+push_sender = A2A::Server::PushSender.new  # no args
+```

data/docs/guides/streaming.md

@@ -0,0 +1,75 @@
+# Streaming Responses
+
+`tasks/sendSubscribe` keeps the HTTP connection open and streams events as your executor progresses. This is ideal for long-running tasks where the client needs incremental feedback.
+
+## Server side — emitting events
+
+Use `ctx.emit_status` and `ctx.emit_artifact` inside your executor:
+
+```ruby
+class StreamingExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status   # publishes TaskStatusUpdateEvent(state: "working", final: false)
+
+    # Stream artifact chunks
+    ["Thinking… ", "Processing… ", "Done!"].each_with_index do |chunk, i|
+      last = i == 2
+      artifact = A2A::Models::Artifact.new(
+        index:      0,
+        parts:      [A2A::Models::Part.text(chunk)],
+        append:     i > 0,   # true for chunks after the first
+        last_chunk: last
+      )
+      ctx.emit_artifact(artifact, append: i > 0, last_chunk: last)
+    end
+
+    ctx.task.complete!
+    ctx.emit_status(final: true)  # signals end of stream
+  end
+end
+```
+
+### Emit methods
+
+| Method | Publishes | `final` |
+|---|---|---|
+| `ctx.emit_status` | `TaskStatusUpdateEvent` | pass `final: true` to close the stream |
+| `ctx.emit_artifact(artifact, append:, last_chunk:)` | `TaskArtifactUpdateEvent` | always `false` |
+
+Always emit `ctx.emit_status(final: true)` as your last event to close the SSE connection cleanly.
+
+---
+
+## Client side — consuming events
+
+Use `Client::SSE#send_subscribe`:
+
+```ruby
+client = A2A.sse_client(url: "http://localhost:9292")
+
+client.send_subscribe(message: A2A::Models::Message.user("go")) do |event|
+  case event
+  when A2A::Models::TaskStatusUpdateEvent
+    puts "[status] #{event.status.state}  final=#{event.final}"
+    break if event.final
+  when A2A::Models::TaskArtifactUpdateEvent
+    print event.artifact.parts.map(&:text).join
+    $stdout.flush
+  end
+end
+```
+
+The block is called for each parsed SSE event. Unrecognized event types yield a plain `Hash`.
+
+---
+
+## AgentCard declaration
+
+Advertise streaming support in your AgentCard:
+
+```ruby
+capabilities = A2A::Models::AgentCapabilities.new(streaming: true)
+```
+
+Clients can check `card.capabilities.streaming` before using `send_subscribe`.

data/docs/index.md

@@ -0,0 +1,98 @@
+# simple_a2a
+
+A Ruby gem implementing the [Agent2Agent (A2A) protocol](https://a2a-protocol.org/latest/) — an open standard by Google and the Linux Foundation for interoperability between AI agents.
+
+`simple_a2a` provides a complete A2A client and server in a single package, built on the async Ruby ecosystem with [Falcon](https://github.com/socketry/falcon) as the recommended HTTP server.
+
+---
+
+## What is A2A?
+
+The Agent2Agent (A2A) protocol defines how AI agents running on different platforms, frameworks, and vendors can discover each other, exchange tasks, and stream results — without vendor lock-in.
+
+- Agents expose a JSON-RPC 2.0 over HTTP endpoint
+- Clients send tasks and receive structured results
+- Streaming uses Server-Sent Events (SSE)
+- Push notifications use webhooks (RS256 JWT)
+- AgentCards describe capabilities and skills
+
+**Protocol Reference:** [https://a2a-protocol.org/latest/](https://a2a-protocol.org/latest/)
+
+---
+
+## At a Glance
+
+```ruby
+require "simple_a2a"
+
+# 1. Implement your agent logic
+class MyExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input = ctx.message.text_content
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        parts: [A2A::Models::Part.text("You said: #{input}")]
+      )
+    ])
+  end
+end
+
+# 2. Describe your agent
+card = A2A::Models::AgentCard.new(
+  name:         "MyAgent",
+  version:      "1.0",
+  capabilities: A2A::Models::AgentCapabilities.new,
+  skills:       [A2A::Models::AgentSkill.new(name: "reply")],
+  interfaces:   [A2A::Models::AgentInterface.new(
+    type: "json-rpc", url: "http://localhost:9292", version: "1.0"
+  )]
+)
+
+# 3. Start the server
+A2A.server(agent_card: card, executor: MyExecutor.new).run
+```
+
+```ruby
+# Client — send a task to any A2A agent
+client = A2A.client(url: "http://localhost:9292")
+task   = client.send_task(message: A2A::Models::Message.user("hello"))
+puts task.status.state   # => "completed"
+```
+
+---
+
+## Features
+
+| Feature | Details |
+|---|---|
+| Protocol | A2A v1.0, backward compatible with v0.3 |
+| Transport | JSON-RPC 2.0 over HTTP(S) |
+| Streaming | Server-Sent Events (SSE) |
+| Push notifications | Webhooks with RS256 JWT signing |
+| Task lifecycle | `submitted → working → completed/failed/canceled` |
+| Discovery | AgentCard endpoint at `GET /agentCard` |
+| Async runtime | `async` gem ecosystem — non-blocking I/O |
+| HTTP server | Falcon (recommended), any Rack-compatible server |
+| HTTP client | `async-http` (`Async::HTTP::Internet`) |
+| Storage | In-memory (thread-safe); pluggable via `Storage::Base` |
+| Routing | Roda with JSON-RPC dispatch |
+| Autoloading | Zeitwerk |
+
+## Runnable demos
+
+The repository includes three demo applications under `examples/`:
+
+| Demo | Shows |
+|---|---|
+| `01_basic_usage` | Agent discovery, `tasks/send`, task listing, task lookup, and error handling |
+| `02_streaming` | `tasks/sendSubscribe` with Server-Sent Events and incremental artifact chunks |
+| `03_llm_research` | Multi-agent routing, parallel streaming LLM calls, evaluator agent, and a Sinatra web client |
+
+Run the basic and streaming demos end-to-end with:
+
+```bash
+bundle exec ruby examples/run 01_basic_usage
+bundle exec ruby examples/run 02_streaming
+```
+
+The LLM research demo requires `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and its demo-specific gems. See the [examples overview](examples/index.md) for setup details.

data/examples/01_basic_usage/client.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/01_basic_usage/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/01_basic_usage/server.rb
+
+require_relative "../common_config"
+
+URL = "http://localhost:9292"
+
+client = A2A.client(url: URL)
+
+# ---------------------------------------------------------------------------
+# 1. Discover the agent
+# ---------------------------------------------------------------------------
+puts "=== Agent Card ==="
+card = client.agent_card
+puts "  Name:        #{card.name}"
+puts "  Version:     #{card.version}"
+puts "  Description: #{card.description}"
+puts "  Skills:      #{card.skills.map(&:name).join(', ')}"
+puts
+
+# ---------------------------------------------------------------------------
+# 2. Send a few tasks
+# ---------------------------------------------------------------------------
+messages = [
+  "world",
+  "Ruby developers",
+  "A2A protocol"
+]
+
+puts "=== Sending Tasks ==="
+task_ids = messages.map do |text|
+  task = client.send_task(message: A2A::Models::Message.user(text))
+
+  reply = task.artifacts.first&.parts&.first&.text || "(no reply)"
+  puts "  [#{task.status.state}] sent: #{text.inspect}"
+  puts "           got: #{reply.inspect}"
+  task.id
+end
+puts
+
+# ---------------------------------------------------------------------------
+# 3. List all tasks
+# ---------------------------------------------------------------------------
+puts "=== Task List ==="
+all_tasks = client.list_tasks
+all_tasks.each do |t|
+  puts "  #{t.id}  state=#{t.status.state}"
+end
+puts "  Total: #{all_tasks.size}"
+puts
+
+# ---------------------------------------------------------------------------
+# 4. Retrieve a single task by ID
+# ---------------------------------------------------------------------------
+puts "=== Retrieve Task ==="
+retrieved = client.get_task(task_ids.first)
+puts "  id:    #{retrieved.id}"
+puts "  state: #{retrieved.status.state}"
+puts "  reply: #{retrieved.artifacts.first&.parts&.first&.text.inspect}"
+puts
+
+# ---------------------------------------------------------------------------
+# 5. Cancel a non-existent task (demonstrates error handling)
+# ---------------------------------------------------------------------------
+puts "=== Error Handling ==="
+begin
+  client.get_task("no-such-task-id")
+rescue A2A::Error => e
+  puts "  Caught expected error: #{e.message}"
+end