simple_a2a 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1b4e2d504e01c9511e9334010acfb9e1ea99314990586789aff6db82f7c31fd
-  data.tar.gz: eda5925b5f758c25980af95081f214d652387d9cc61bbd37f0bb6f31d2aa7dbc
+  metadata.gz: 8200755c9d568b3b1161815a2dfd8df190efe773ae946a00fafcfddd25b1ca4e
+  data.tar.gz: a5f112a8138f111d137b1a443c674a309c0ad98c5c6f5b8473e4c5d3af42d316
 SHA512:
-  metadata.gz: 1074249a5196cd4f0c533ef12b4662f4897d03a64f9d626429f0e7cbbd1653c6822e566afa4467793fe3d934d5e9d2451079fdcd5e1ad00159b505af814f4e02
-  data.tar.gz: 003b13cec22786ee19363f1afa1bdeee064a79a0a600b0b73a3343df6167611dc5b93c8c45fc6522b637c5ae5fde6c322836d6b05743fd53a0a49275ce12786b
+  metadata.gz: 39509e60e4665ca244831830f6b9c5cb4e3de384c98c7e5d5ae74ab15bdce5c06fb942fb85a6738a11e2d6080f8ab2c3c6334d0be02f58e04bd1f364a9df1231
+  data.tar.gz: d6c85963a895435cffa1b3ec28ad7bc7506d168274ae2281b4e7c590ff0d4b48387cb97a4f249aaf7df01621ade3b8aeaf7e3de14e2e35cfad42625600084635

data/CHANGELOG.md

@@ -1,5 +1,72 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-09
+
+### Added
+
+- `tasks/resubscribe` — attach an SSE stream to an existing running task (A2A `SubscribeToTask`
+  operation). The first event is the current Task snapshot (spec requirement); subsequent events
+  mirror those emitted by the executor in real time.
+- `Client::SSE#resubscribe(task_id:, &block)` — client-side counterpart for `tasks/resubscribe`.
+- `Server::TaskBroadcast` — lock-free, fiber-scheduler-aware fan-out broadcaster. Replaces the
+  anonymous streaming router and `EventRouter`. Each running task gets one broadcast; each SSE
+  subscriber (original or resubscribed) gets its own `RactorQueue`.
+- `Server::BroadcastRegistry` — thread-safe `task_id → TaskBroadcast` map held at the App class
+  level. Allows `tasks/resubscribe` and `tasks/cancel` to locate a live broadcast.
+- `tasks/pushNotification/set|get|delete|list` — push notification config CRUD now fully
+  implemented. Configs are stored per task ID in a new `Server::PushConfigStore`; `set` validates
+  the task exists and that `webhookUrl` is present before storing.
+- `Server::PushConfigStore` — thread-safe in-memory store for `PushNotificationConfig` objects,
+  keyed by task ID. One instance is created per `Server::App` automatically.
+- `examples/04_resubscribe` — two concurrent SSE subscribers demonstrating snapshot-on-join,
+  independent fan-out, and single-completion guarantees.
+- `examples/05_cancellation` — three concurrent `tasks/sendSubscribe` streams; one task is
+  cancelled mid-flight while the others complete normally.
+- `examples/06_push_notifications` — full push notification lifecycle: submit task, register
+  webhook, receive out-of-band HTTP POSTs per step, then get/list/delete the config with no
+  open SSE connection required.
+- `examples/07_agent_chaining` — three agents (`ReverseAgent`, `ShoutAgent`, `PipelineAgent`)
+  on one port via `A2A.multi_server`; the pipeline executor chains to the other two agents over
+  the protocol, invisible to the client.
+- `examples/08_interrupted_states` — `input_required` and `auth_required` interrupted states
+  demonstrated with `OrderAgent` (pauses for user input) and `VaultAgent` (blocks on wrong
+  token); each follow-up turn is a separate `tasks/send` threaded by `message.context_id`.
+- `examples/09_multipart` — all four `Part` types in one artifact: text summary, JSON metadata,
+  base64-encoded binary CSV, and URL reference; client uses `text?/json?/raw?/url?` predicates.
+- `examples/10_auth_headers` — `headers:` option on `A2A.client` with a Bearer token middleware;
+  agent card discovery is public while RPC calls require `Authorization: Bearer <token>`.
+- `examples/11_sqlite_storage` — persistent task storage across server restarts via
+  `SqliteStorage < A2A::Storage::Base` (WAL mode, mutex, JSON blobs); Brewfile + Gemfile pattern
+  keeps SQLite dependency out of the main gem.
+- MkDocs documentation pages for examples 05–11 (`cancellation`, `push-notifications`,
+  `agent-chaining`, `interrupted-states`, `multipart`, `auth-headers`, `sqlite-storage`).
+- `compare_agent2agent.md` — side-by-side comparison of A2A protocol operations at the repo root.
+
+### Changed
+
+- `handle_cancel` now routes cancellation events through the live broadcast so SSE subscribers
+  observe the `canceled` state update in real time.
+- `Server::Base` and `Server::MultiAgent` no longer create an `EventRouter`; they inject a fresh
+  `BroadcastRegistry` into each App subclass instead.
+- `Server::Base` now accepts a `push_config_store:` keyword so the executor and the App share
+  the same store instance (fixes injection gap).
+- README Examples section expanded to an 11-row table; `docs/examples/index.md` rebuilt with
+  a 3×4 SVG grid covering all demos.
+
+### Fixed
+
+- Removed phantom `simple_flow` runtime dependency from gemspec.
+- Added missing `digest` require (fixes JWT signing in push notification delivery).
+
+### Removed
+
+- `Server::EventRouter` and its `TypedBus`-based pub/sub — superseded by `TaskBroadcast`.
+- `typed_bus` runtime dependency — removed entirely.
+
+### Dependencies
+
+- Added `ractor_queue ~> 0.2` runtime dependency (replaces `typed_bus`).
+
 ## [0.1.0] - 2026-05-07
 
 - Initial release

data/README.md

@@ -1,44 +1,62 @@
 # 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.
-
-## Documentation
-
-The full documentation website is available at [https://madbomber.github.io/simple_a2a](https://madbomber.github.io/simple_a2a).
+<table>
+  <tr>
+    <td width="40%">
+      <img src="docs/assets/images/simple_a2a.jpg" alt="simple_a2a - AI agents communicating" width="100%">
+    </td>
+    <td width="60%" valign="top">
+      <strong>A Ruby gem implementing the <a href="https://a2a-protocol.org/latest/">Agent2Agent (A2A) protocol</a></strong>
+      <br><br>
+      A complete A2A client and server in a single package, built on the async Ruby ecosystem with Falcon as the recommended HTTP server.
+      <ul>
+        <li>Full A2A v1.0 protocol support (backward compatible with v0.3)</li>
+        <li>JSON-RPC 2.0 over HTTP(S) — primary binding</li>
+        <li>Server-Sent Events (SSE) for streaming responses (<code>tasks/sendSubscribe</code> and <code>tasks/resubscribe</code>)</li>
+        <li>Push notifications via webhooks (RS256 JWT)</li>
+        <li>Task lifecycle management (<code>submitted → working → completed/failed/canceled</code>)</li>
+        <li>AgentCard discovery endpoint at <code>GET /agentCard</code></li>
+        <li>Multi-agent hosting with path-based routing via <code>A2A.multi_server</code></li>
+        <li>Async-first via the <code>async</code> gem ecosystem (Falcon + async-http)</li>
+        <li>Lock-free SSE fan-out via <code>RactorQueue</code> — multiple concurrent subscribers per task</li>
+        <li>Rack-compatible server with Roda routing</li>
+        <li>Zeitwerk autoloading — top-level module is <code>A2A</code></li>
+        <li><a href="https://madbomber.github.io/simple_a2a">Full documentation website</a></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+## MCP vs. A2A
+
+Two open protocols address different dimensions of AI agent integration — and they are designed to complement each other.
+
+**MCP — Vertical Integration (Agent ↕ Environment)**
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), introduced by Anthropic in November 2024, defines how an AI agent connects to the tools, data sources, and services in its environment — file systems, databases, APIs, browsers, and code execution engines. MCP uses a client-server model where the agent is the client and each external capability is a server. This is *vertical* integration: the agent reaches downward into its local context and outward into external services through a uniform interface.
+
+**A2A — Horizontal Integration (Agent ↔ Agent)**
+
+The [Agent2Agent Protocol](https://a2a-protocol.org/latest/) (A2A), introduced by Google in April 2025 and donated to the Linux Foundation for vendor-neutral governance, defines how autonomous agents running on different platforms, frameworks, and vendors can discover one another, delegate tasks, and stream results in real time. This is *horizontal* integration: peer agents — each with its own specialization, runtime, and vendor — collaborate as equals across organizational and technology boundaries.
+
+**Together**
+
+MCP and A2A are complementary. A single agent can use MCP to access its tools and A2A to delegate subtasks to peer agents. `simple_a2a` implements the A2A layer.
 
 ## Lineage
 
 `simple_a2a` is the successor to my earlier Ruby gem, `simple_acp`. That gem implemented the Agent Communication Protocol (ACP), which IBM Research introduced through the BeeAI project for interoperable agent communication. ACP later merged into A2A under the Linux Foundation, with the ACP team contributing its technology and expertise to the A2A effort.
 
-A2A itself was created by Google and then donated to the Linux Foundation for neutral, open governance. The current A2A specification is maintained by the Linux Foundation-hosted [Agent2Agent project](https://github.com/a2aproject/A2A) and published at [a2a-protocol.org](https://a2a-protocol.org/latest/).
-
 > My opinion: the A2A specification is still a little jagged in places. A simple example is that it does not clearly cover whether an A2A server is expected to host only one agent or may host multiple agents. That is a minor example, but it points to the kind of operational detail the specification still needs to tighten up.
 
 References:
 
+- Anthropic: [Introducing the Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) (November 2024)
+- Google Developers Blog: [A2A: A new era of agent interoperability](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) (April 2025)
 - IBM Research: [Agent Communication Protocol](https://research.ibm.com/projects/agent-communication-protocol)
 - BeeAI announcement: [ACP Joins Forces with A2A Under the Linux Foundation](https://github.com/orgs/i-am-bee/discussions/5)
 - Linux Foundation: [Launch of the Agent2Agent Protocol Project](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents)
-
-## Protocol Reference
-
-- **Official A2A Specification:** [https://a2a-protocol.org/latest/](https://a2a-protocol.org/latest/)
-- **A2A Project on GitHub:** [https://github.com/a2aproject/A2A](https://github.com/a2aproject/A2A)
-
-## Features
-
-- Full A2A v1.0 protocol support (backward compatible with v0.3)
-- JSON-RPC 2.0 over HTTP(S) — primary binding
-- Server-Sent Events (SSE) for streaming responses
-- Push notifications via webhooks (RS256 JWT)
-- Task lifecycle management (`submitted → working → completed/failed/canceled`)
-- AgentCard discovery endpoint at `GET /agentCard`
-- Multi-agent hosting with path-based routing via `A2A.multi_server`
-- Async-first via the `async` gem ecosystem (Falcon + async-http)
-- Rack-compatible server with Roda routing
-- Zeitwerk autoloading — top-level module is `A2A`
+- A2A Project on GitHub: [https://github.com/a2aproject/A2A](https://github.com/a2aproject/A2A)
 
 ## Installation
 
@@ -128,7 +146,7 @@ end
 ```
 
 ```ruby
-# Client — consume SSE events
+# Client — start a streaming task
 client = A2A.sse_client(url: "http://localhost:9292")
 
 client.send_subscribe(message: A2A::Models::Message.user("go")) do |event|
@@ -141,6 +159,19 @@ client.send_subscribe(message: A2A::Models::Message.user("go")) do |event|
 end
 ```
 
+```ruby
+# Client — reattach to an already-running task
+# First event is the current Task snapshot; subsequent events are the live stream.
+client.resubscribe(task_id: "existing-task-id") do |event|
+  case event
+  when Hash
+    puts "task snapshot: #{event['status']['state']}"
+  when A2A::Models::TaskStatusUpdateEvent
+    puts "status: #{event.status.state} (final=#{event.final})"
+  end
+end
+```
+
 ## Multi-agent server
 
 Use `A2A.multi_server` to host multiple A2A agents in one Falcon process, with each agent mounted at its own path:
@@ -155,26 +186,35 @@ A2A.multi_server(
 ).run
 ```
 
-Each mounted agent has its own AgentCard, executor, storage, and event router.
+Each mounted agent has its own AgentCard, executor, storage, and broadcast registry.
 
 ## Examples
 
-The repository includes three runnable demo apps:
+The repository includes eleven runnable demo applications:
 
-| 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 |
+| # | Demo | What it shows |
+|---|---|---|
+| 01 | Basic Usage | Agent discovery, `tasks/send`, task listing, task lookup, error handling |
+| 02 | Streaming | `tasks/sendSubscribe`, SSE, incremental artifact chunks |
+| 03 | LLM Research | `multi_server`, parallel SSE agents, evaluator pattern, web client |
+| 04 | Resubscribe | `tasks/resubscribe`, concurrent SSE subscribers, mid-stream join |
+| 05 | Cancellation | `tasks/cancel`, concurrent tasks, cooperative cancellation |
+| 06 | Push Notifications | `tasks/pushNotification` CRUD, webhook delivery, out-of-band events |
+| 07 | Agent Chaining | `A2A.client` inside an executor, agent-to-agent delegation |
+| 08 | Interrupted States | `input_required`, `auth_required`, multi-turn `context_id` threading |
+| 09 | Multipart Artifacts | `Part.text`, `Part.json`, `Part.binary`, `Part.from_url`, predicates |
+| 10 | Auth Headers | `A2A.client(headers:)`, Bearer token, Rack middleware composition |
+| 11 | SQLite Storage | `Storage::Base` injection, WAL persistence, cross-restart survival |
 
-Run the basic and streaming demos end-to-end:
+Run any demo end-to-end from the repository root:
 
 ```bash
 bundle exec ruby examples/run 01_basic_usage
-bundle exec ruby examples/run 02_streaming
+bundle exec ruby examples/run 05_cancellation
+bundle exec ruby examples/run 11_sqlite_storage
 ```
 
-The LLM research demo requires `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and demo-specific gems. See the full documentation for setup details.
+Demo 03 requires `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and additional gems (`ruby_llm`, `async-http-faraday`, `sinatra`). Demo 11 has its own `Gemfile` and `Brewfile`; its `run` script handles setup automatically. See [`examples/README.md`](examples/README.md) for full details on each demo.
 
 ## Development