simple_a2a 0.1.0 → 0.3.0

data/docs/architecture/index.md

@@ -6,17 +6,18 @@
 A2A
 ├── Models      — data classes (Task, Message, Part, Artifact, AgentCard, …)
 ├── Server      — HTTP server, routing, executor base, event fan-out
-│   ├── App          (Roda JSON-RPC router)
-│   ├── Base         (server bootstrap + Falcon runner)
-│   ├── AgentExecutor (base class for your agent logic)
-│   ├── Context      (per-request helper passed to executor)
-│   ├── ResumeContext (Context + resume_message for interrupted tasks)
-│   ├── EventRouter  (TypedBus SSE fan-out)
-│   ├── PushSender   (webhook delivery with JWT signing)
-│   └── FalconRunner (Falcon adapter)
+│   ├── App               (Roda JSON-RPC router)
+│   ├── Base              (server bootstrap + Falcon runner)
+│   ├── AgentExecutor     (base class for your agent logic)
+│   ├── Context           (per-request helper passed to executor)
+│   ├── ResumeContext     (Context + resume_message for interrupted tasks)
+│   ├── TaskBroadcast     (RactorQueue-based SSE fan-out per running task)
+│   ├── BroadcastRegistry (task_id → TaskBroadcast map, shared across requests)
+│   ├── PushSender        (webhook delivery with JWT signing)
+│   └── FalconRunner      (Falcon adapter)
 ├── Client      — async HTTP client
 │   ├── Base    (JSON-RPC client over async/http)
-│   └── SSE     (streaming subscribe client)
+│   └── SSE     (streaming subscribe + resubscribe client)
 ├── Storage     — task persistence
 │   ├── Base    (abstract interface)
 │   └── Memory  (in-process, thread-safe)
@@ -33,21 +34,22 @@ App (Roda)
     │  JSON-RPC parse + dispatch
     │
     ▼
-handle_send
+handle_send / handle_send_subscribe
     │  creates Task (submitted)
-    │  builds Context
+    │  builds Context (with TaskBroadcast as event_router)
     │
     ▼
 Executor#call(ctx)          ← your code lives here
     │  ctx.task.start!
-    │  ctx.emit_artifact(…)  → EventRouter → SSE subscribers
+    │  ctx.emit_artifact(…)  → TaskBroadcast → RactorQueue(s) → SSE subscriber(s)
     │  ctx.task.complete!(…)
     │
     ▼
 Storage#save(task)
     │
     ▼
-JsonRpc::Response (task hash) → HTTP response
+JsonRpc::Response (task hash) → HTTP response   [tasks/send]
+SSE stream closes             → HTTP body ends  [tasks/sendSubscribe / tasks/resubscribe]
 ```
 
 ## Key design decisions
@@ -58,6 +60,6 @@ JsonRpc::Response (task hash) → HTTP response
 
 **One executor instance** — `Server::Base` holds a single executor object. For concurrent requests, executors must be stateless (or use per-call state inside `#call`).
 
-**Pluggable storage** — `Storage::Base` defines the interface (`save`, `find!`, `list`, `delete`). Swap in Redis or PostgreSQL by subclassing and passing your implementation to `Server::Base`.
+**Pluggable storage** — `Storage::Base` defines the interface (`save`, `find`, `list`, `delete`). `find!` (raises on missing) is a convenience method on `Storage::Memory` only — not part of the required interface. Swap in Redis or PostgreSQL by subclassing and passing your implementation to `Server::Base`.
 
-**EventRouter** — wraps `TypedBus::MessageBus` to provide per-task SSE channels. Channels are opened on first publish and closed when the SSE connection ends. `subscribe` transparently unwraps `TypedBus::Delivery` and calls `ack!`.
+**TaskBroadcast + BroadcastRegistry** — each streaming task gets one `TaskBroadcast`, which holds one `RactorQueue` per SSE subscriber. The broadcast is registered in `BroadcastRegistry` for the duration of the task so that `tasks/resubscribe` and `tasks/cancel` can locate it by task ID. `RactorQueue#async_push` / `#async_pop` cooperate with the Falcon fiber scheduler via `sleep(0)`, keeping the event loop non-blocking. Multiple concurrent subscribers (original `sendSubscribe` and any number of `resubscribe` clients) each receive every event independently.

data/docs/architecture/protocol.md

@@ -42,6 +42,7 @@ All A2A communication uses **JSON-RPC 2.0 over HTTP POST** to a single endpoint
 |---|---|
 | `tasks/send` | Send a message, execute synchronously, return completed task |
 | `tasks/sendSubscribe` | Send a message, stream events via SSE |
+| `tasks/resubscribe` | Attach an SSE stream to an existing running task |
 | `tasks/get` | Retrieve a task by ID |
 | `tasks/list` | List all tasks |
 | `tasks/cancel` | Cancel a non-terminal task |
@@ -99,7 +100,9 @@ Interrupted tasks can be resumed by sending a new message.
 
 ## Streaming (SSE)
 
-`tasks/sendSubscribe` keeps the HTTP connection open and streams `text/event-stream` events:
+Both `tasks/sendSubscribe` and `tasks/resubscribe` keep the HTTP connection open and stream `text/event-stream` events.
+
+**`tasks/sendSubscribe`** — creates a new task and immediately begins streaming:
 
 ```
 data: {"jsonrpc":"2.0","result":{"type":"TaskStatusUpdateEvent","taskId":"…","status":{"state":"working"},"final":false}}
@@ -109,4 +112,16 @@ data: {"jsonrpc":"2.0","result":{"type":"TaskArtifactUpdateEvent","taskId":"…"
 data: {"jsonrpc":"2.0","result":{"type":"TaskStatusUpdateEvent","taskId":"…","status":{"state":"completed"},"final":true}}
 ```
 
+**`tasks/resubscribe`** — attaches to an existing running task. The first event is always the current Task snapshot (no `type` field); subsequent events are the live stream:
+
+```
+data: {"jsonrpc":"2.0","result":{"id":"…","contextId":"…","status":{"state":"working",…},"artifacts":[]}}
+
+data: {"jsonrpc":"2.0","result":{"type":"TaskArtifactUpdateEvent","taskId":"…","artifact":{…},"final":false}}
+
+data: {"jsonrpc":"2.0","result":{"type":"TaskStatusUpdateEvent","taskId":"…","status":{"state":"completed"},"final":true}}
+```
+
+`tasks/resubscribe` returns `UnsupportedOperationError` if the task is already in a terminal state or is not currently streaming. Multiple clients may subscribe to the same task concurrently.
+
 Events with `"final": true` signal that the stream is complete.

data/docs/examples/agent-chaining.md

@@ -0,0 +1,107 @@
+# 07 Agent Chaining
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 07_agent_chaining
+```
+
+**What it shows:** one agent calling peer agents using `A2A.client` inside its executor — the same client interface an external caller would use.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/07_agent_chaining/server.rb` | Three agents at `/reverse`, `/shout`, `/pipeline`; `PipelineExecutor` chains the other two |
+| `examples/07_agent_chaining/client.rb` | External client that speaks only to `/pipeline`; the internal delegation is invisible to it |
+
+---
+
+## The scenario
+
+The demo mounts three agents on one server:
+
+| Path | Agent | What it does |
+|---|---|---|
+| `/reverse` | `ReverseAgent` | Returns the input string with characters reversed |
+| `/shout` | `ShoutAgent` | Returns the input string uppercased with `!!!` appended |
+| `/pipeline` | `PipelineAgent` | Calls `/reverse` then `/shout` internally and returns the final result |
+
+The external client sends one message to `/pipeline`. The pipeline executor calls the other two agents in sequence using `A2A.client` and returns their combined output. The external client never learns that two additional A2A calls were made internally.
+
+---
+
+## Server — `PipelineExecutor`
+
+The executor holds pre-built `A2A.client` instances pointing to its peer agents:
+
+```ruby
+class PipelineExecutor < A2A::Server::AgentExecutor
+  def initialize(reverse_url:, shout_url:)
+    @reverse_client = A2A.client(url: reverse_url)
+    @shout_client   = A2A.client(url: shout_url)
+  end
+
+  def call(ctx)
+    input = ctx.message.text_content.strip
+
+    reversed = @reverse_client
+      .send_task(message: A2A::Models::Message.user(input))
+      .artifacts.first&.parts&.first&.text
+
+    shouted = @shout_client
+      .send_task(message: A2A::Models::Message.user(reversed))
+      .artifacts.first&.parts&.first&.text
+
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "result",
+        parts: [A2A::Models::Part.text(shouted)]
+      )
+    ])
+  end
+end
+```
+
+All three agents are mounted on one port via `A2A.multi_server`:
+
+```ruby
+A2A.multi_server(
+  agents: {
+    "/reverse"  => { agent_card: reverse_card,  executor: ReverseExecutor.new },
+    "/shout"    => { agent_card: shout_card,     executor: ShoutExecutor.new },
+    "/pipeline" => { agent_card: pipeline_card,  executor: pipeline_executor }
+  },
+  port: 9292
+).run
+```
+
+---
+
+## Client flow
+
+The external client discovers all three agent cards then calls the pipeline:
+
+```ruby
+client = A2A.client(url: "http://localhost:9292/pipeline")
+task   = client.send_task(message: A2A::Models::Message.user("hello world"))
+puts task.artifacts.first.parts.first.text
+# => "DLROW OLLEH!!!"
+```
+
+The client also fetches agent cards from all three paths to show they are independently discoverable.
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| Agent-to-agent delegation | An executor uses `A2A.client` to call peer agents during task execution |
+| `A2A.multi_server` | Three agents hosted at `/reverse`, `/shout`, `/pipeline` on one port |
+| Agent Card discovery | Client discovers all three cards; pipeline card describes its composed capability |
+| `tasks/send` | Sub-agents called synchronously within the pipeline executor's fiber |
+| Protocol transparency | Internal A2A calls use the same JSON-RPC wire format as external calls |
+| Composability | Any agent can act as both a server (to its caller) and a client (to its dependencies) |

data/docs/examples/auth-headers.md

@@ -0,0 +1,105 @@
+# 10 Auth Headers
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 10_auth_headers
+```
+
+**What it shows:** injecting custom HTTP headers (Bearer token) into every client request, and wrapping the server with Rack middleware to enforce them.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/10_auth_headers/server.rb` | `BearerAuthMiddleware` wraps the standard `rack_app`; agent card stays public |
+| `examples/10_auth_headers/client.rb` | Two clients — one without headers (rejected) and one with (accepted) |
+
+---
+
+## The scenario
+
+The server enforces a Bearer token on all `POST /` (RPC) requests. `GET /agentCard` is deliberately left public so agents remain discoverable without credentials.
+
+Two clients are created with the same URL:
+
+```ruby
+unauth_client = A2A.client(url: URL)
+auth_client   = A2A.client(url: URL, headers: { "Authorization" => "Bearer #{TOKEN}" })
+```
+
+- `unauth_client.agent_card` → succeeds (GET is public)
+- `unauth_client.send_task(...)` → raises `A2A::Error` ("Unauthorized")
+- `auth_client.send_task(...)` → succeeds
+
+---
+
+## Server — Rack middleware composition
+
+The middleware pattern keeps the library unchanged:
+
+```ruby
+class BearerAuthMiddleware
+  def initialize(app, token:)
+    @app   = app
+    @token = token
+  end
+
+  def call(env)
+    if env["REQUEST_METHOD"] == "POST"
+      auth = env["HTTP_AUTHORIZATION"].to_s
+      unless auth == "Bearer #{@token}"
+        body = JSON.generate({
+          "jsonrpc" => "2.0", "id" => nil,
+          "error"   => { "code" => -32_000, "message" => "Unauthorized: valid Bearer token required" }
+        })
+        return [200, { "Content-Type" => "application/json" }, [body]]
+      end
+    end
+    @app.call(env)
+  end
+end
+
+inner_app = A2A.server(agent_card: card, executor: SecureEchoExecutor.new).rack_app
+auth_app  = BearerAuthMiddleware.new(inner_app, token: VALID_TOKEN)
+A2A::Server::FalconRunner.new(auth_app, port: 9292).run
+```
+
+The middleware returns a JSON-RPC shaped error body (not a bare HTTP 401) so the `A2A::Error` rescue path on the client works without special-casing.
+
+---
+
+## The `headers:` option
+
+`A2A.client(headers:)` and `A2A.sse_client(headers:)` accept any `Hash` of header name → value pairs, which are merged into every request:
+
+```ruby
+# Bearer token
+A2A.client(url: URL, headers: { "Authorization" => "Bearer secret" })
+
+# API key
+A2A.client(url: URL, headers: { "X-Api-Key" => "key123" })
+
+# Multiple headers
+A2A.client(url: URL, headers: {
+  "Authorization" => "Bearer token",
+  "X-Tenant-Id"   => "acme"
+})
+```
+
+The same option applies to `A2A.sse_client` for streaming subscriptions.
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| `A2A.client(headers:)` | `headers: { "Authorization" => "Bearer token" }` appended to every request |
+| `AgentCard` public discovery | `GET /agentCard` succeeds without authentication — agents are discoverable |
+| Bearer token authentication | `Authorization: Bearer <token>` header checked on all POST (RPC) requests |
+| Rack middleware composition | `BearerAuthMiddleware.new(rack_app, token:)` wraps the standard app without library changes |
+| JSON-RPC error on rejection | Middleware returns a well-formed JSON-RPC error body so the client can rescue `A2A::Error` |
+| Header flexibility | The same `headers:` option supports API keys, custom schemes, and any HTTP header |

data/docs/examples/cancellation.md

@@ -0,0 +1,105 @@
+# 05 Cancellation
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 05_cancellation
+```
+
+**What it shows:** how to cancel an in-flight task mid-execution while other concurrent tasks run to completion.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/05_cancellation/server.rb` | `SlowExecutor` that runs 10 one-second steps and checks `ctx.task.terminal?` between each step |
+| `examples/05_cancellation/client.rb` | Starts three concurrent SSE subscriptions, cancels the middle task after 3 s, verifies final states |
+
+---
+
+## The scenario
+
+Three tasks (A, B, C) start simultaneously via `tasks/sendSubscribe`. Each runs a 10-step loop with 1-second pauses — a 10-second total runtime without intervention. After 3 seconds the client calls `tasks/cancel` on Task B. Task B transitions to `canceled`; Tasks A and C run to completion unaffected.
+
+This demonstrates three protocol guarantees:
+
+1. **Mid-flight cancellation** — `tasks/cancel` interrupts a running task without touching sibling tasks.
+2. **Cooperative cancellation** — the executor checks `ctx.task.terminal?` between steps and exits cleanly when cancelled.
+3. **Terminal state isolation** — the `canceled` state is terminal; subsequent executor steps are skipped.
+
+---
+
+## Server — `SlowExecutor`
+
+The executor emits one status event per step and checks for cancellation between steps:
+
+```ruby
+class SlowExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status
+
+    10.times do |i|
+      break if ctx.task.terminal?   # exit early if cancelled
+      sleep 1
+      ctx.emit_artifact(A2A::Models::Artifact.new(
+        parts: [A2A::Models::Part.text("step #{i + 1}/10")]
+      ))
+    end
+
+    return if ctx.task.terminal?
+    ctx.task.complete!
+    ctx.emit_status(final: true)
+  end
+end
+```
+
+The `AgentCapabilities` declares `streaming: true` so clients know to use `tasks/sendSubscribe`.
+
+---
+
+## Client — concurrent tasks with mid-flight cancel
+
+Three SSE subscriptions run in separate threads. Each thread captures its task ID from the first status event:
+
+```ruby
+task_ids = {}
+mutex    = Mutex.new
+
+threads = %w[A B C].map do |label|
+  Thread.new do
+    A2A.sse_client(url: URL).send_subscribe(message: ...) do |event|
+      if event.is_a?(A2A::Models::TaskStatusUpdateEvent)
+        mutex.synchronize { task_ids[label] ||= event.task_id }
+      end
+    end
+  end
+end
+
+sleep 3 until task_ids.key?("B")
+client.cancel_task(task_ids["B"])
+threads.each(&:join)
+```
+
+After all threads finish, the client calls `client.get_task` for each ID and asserts the expected states:
+
+```
+Task A: completed  ✓
+Task B: canceled   ✓
+Task C: completed  ✓
+```
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| `tasks/cancel` | Client sends a cancel request by task ID while the task is mid-execution |
+| `canceled` terminal state | Task B transitions to `canceled`; its SSE stream receives a final status event and closes |
+| Concurrent task isolation | Tasks A and C are unaffected by the cancellation of task B |
+| `AgentExecutor#cancel` | Default implementation calls `task.cancel!` and emits a final status event |
+| `TaskState` lifecycle | `submitted → working → canceled` vs `submitted → working → completed` |
+| Cooperative cancellation | Executor checks `ctx.task.terminal?` between steps and exits early when cancelled |

data/docs/examples/index.md

@@ -1,52 +1,112 @@
 # Examples
 
-The `examples/` directory contains runnable demo applications that exercise the gem from a client and server process. Each demo uses `examples/common_config.rb`, which adds the repository `lib/` directory to `$LOAD_PATH` before requiring `simple_a2a`, so the examples run against the local checkout.
+The `examples/` directory contains eleven runnable demo applications that exercise the gem from a client and server process. Each demo uses `examples/common_config.rb`, which adds the repository `lib/` directory to `$LOAD_PATH` before requiring `simple_a2a`, so the examples run against the local checkout.
 
-<svg viewBox="0 0 900 330" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="examples-title examples-desc">
+<svg viewBox="0 0 830 510" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="examples-title examples-desc">
   <title id="examples-title">simple_a2a example applications</title>
-  <desc id="examples-desc">Dark themed transparent-background diagram showing the three example applications and the A2A capabilities they demonstrate.</desc>
+  <desc id="examples-desc">Dark themed diagram showing all eleven example applications in a 3×4 grid with the A2A capabilities each demonstrates.</desc>
   <defs>
-    <linearGradient id="blue" x1="0" x2="1">
-      <stop offset="0" stop-color="#38bdf8"/>
-      <stop offset="1" stop-color="#2563eb"/>
-    </linearGradient>
-    <linearGradient id="green" x1="0" x2="1">
-      <stop offset="0" stop-color="#34d399"/>
-      <stop offset="1" stop-color="#16a34a"/>
-    </linearGradient>
-    <linearGradient id="amber" x1="0" x2="1">
-      <stop offset="0" stop-color="#fbbf24"/>
-      <stop offset="1" stop-color="#f97316"/>
-    </linearGradient>
-    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
-      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#000000" flood-opacity="0.35"/>
+    <linearGradient id="eg-blue"   x1="0" x2="1"><stop offset="0" stop-color="#38bdf8"/><stop offset="1" stop-color="#2563eb"/></linearGradient>
+    <linearGradient id="eg-green"  x1="0" x2="1"><stop offset="0" stop-color="#34d399"/><stop offset="1" stop-color="#16a34a"/></linearGradient>
+    <linearGradient id="eg-amber"  x1="0" x2="1"><stop offset="0" stop-color="#fbbf24"/><stop offset="1" stop-color="#f97316"/></linearGradient>
+    <linearGradient id="eg-violet" x1="0" x2="1"><stop offset="0" stop-color="#a78bfa"/><stop offset="1" stop-color="#7c3aed"/></linearGradient>
+    <linearGradient id="eg-teal"   x1="0" x2="1"><stop offset="0" stop-color="#2dd4bf"/><stop offset="1" stop-color="#0891b2"/></linearGradient>
+    <linearGradient id="eg-rose"   x1="0" x2="1"><stop offset="0" stop-color="#fb7185"/><stop offset="1" stop-color="#e11d48"/></linearGradient>
+    <filter id="eg-glow" x="-10%" y="-10%" width="120%" height="120%">
+      <feDropShadow dx="0" dy="4" stdDeviation="6" flood-color="#000" flood-opacity="0.35"/>
     </filter>
   </defs>
-  <g fill="none" stroke="#334155" stroke-width="2">
-    <path d="M295 165H365"/>
-    <path d="M535 165H605"/>
+
+  <!-- Row 0 -->
+  <g filter="url(#eg-glow)">
+    <rect x="15"  y="15"  width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-blue)"   stroke-width="2"/>
+    <rect x="285" y="15"  width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-green)"  stroke-width="2"/>
+    <rect x="555" y="15"  width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-amber)"  stroke-width="2"/>
+  </g>
+  <!-- Row 1 -->
+  <g filter="url(#eg-glow)">
+    <rect x="15"  y="135" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-blue)"   stroke-width="2"/>
+    <rect x="285" y="135" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-amber)"  stroke-width="2"/>
+    <rect x="555" y="135" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-green)"  stroke-width="2"/>
   </g>
-  <g filter="url(#glow)">
-    <rect x="45" y="65" width="250" height="200" rx="14" fill="#0f172a" stroke="url(#blue)" stroke-width="2"/>
-    <rect x="325" y="65" width="250" height="200" rx="14" fill="#0f172a" stroke="url(#green)" stroke-width="2"/>
-    <rect x="605" y="65" width="250" height="200" rx="14" fill="#0f172a" stroke="url(#amber)" stroke-width="2"/>
+  <!-- Row 2 -->
+  <g filter="url(#eg-glow)">
+    <rect x="15"  y="255" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-violet)" stroke-width="2"/>
+    <rect x="285" y="255" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-amber)"  stroke-width="2"/>
+    <rect x="555" y="255" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-teal)"   stroke-width="2"/>
   </g>
-  <g font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
-    <text x="70" y="108" fill="#e2e8f0" font-size="24" font-weight="700">01 Basic Usage</text>
-    <text x="70" y="145" fill="#93c5fd" font-size="16">JSON-RPC request/response</text>
-    <text x="70" y="180" fill="#cbd5e1" font-size="15">agent card discovery</text>
-    <text x="70" y="205" fill="#cbd5e1" font-size="15">send, list, and get tasks</text>
-    <text x="70" y="230" fill="#cbd5e1" font-size="15">client error handling</text>
-    <text x="350" y="108" fill="#e2e8f0" font-size="24" font-weight="700">02 Streaming</text>
-    <text x="350" y="145" fill="#86efac" font-size="16">SSE task subscription</text>
-    <text x="350" y="180" fill="#cbd5e1" font-size="15">working/final statuses</text>
-    <text x="350" y="205" fill="#cbd5e1" font-size="15">append artifact chunks</text>
-    <text x="350" y="230" fill="#cbd5e1" font-size="15">incremental client output</text>
-    <text x="630" y="108" fill="#e2e8f0" font-size="24" font-weight="700">03 LLM Research</text>
-    <text x="630" y="145" fill="#fcd34d" font-size="16">multi-agent orchestration</text>
-    <text x="630" y="180" fill="#cbd5e1" font-size="15">Anthropic + OpenAI agents</text>
-    <text x="630" y="205" fill="#cbd5e1" font-size="15">evaluator agent</text>
-    <text x="630" y="230" fill="#cbd5e1" font-size="15">CLI and web clients</text>
+  <!-- Row 3 -->
+  <g filter="url(#eg-glow)">
+    <rect x="15"  y="375" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-rose)"   stroke-width="2"/>
+    <rect x="285" y="375" width="260" height="110" rx="10" fill="#0f172a" stroke="url(#eg-violet)" stroke-width="2"/>
+  </g>
+
+  <g font-family="Inter, ui-sans-serif, system-ui, sans-serif">
+    <!-- 01 Basic Usage -->
+    <text x="30"  y="47"  fill="#e2e8f0" font-size="17" font-weight="700">01 Basic Usage</text>
+    <text x="30"  y="67"  fill="#93c5fd" font-size="12">JSON-RPC request/response</text>
+    <text x="30"  y="85"  fill="#cbd5e1" font-size="12">agent card discovery</text>
+    <text x="30"  y="103" fill="#cbd5e1" font-size="12">tasks/send · get · list · errors</text>
+
+    <!-- 02 Streaming -->
+    <text x="300" y="47"  fill="#e2e8f0" font-size="17" font-weight="700">02 Streaming</text>
+    <text x="300" y="67"  fill="#86efac" font-size="12">tasks/sendSubscribe · SSE</text>
+    <text x="300" y="85"  fill="#cbd5e1" font-size="12">working / completed status</text>
+    <text x="300" y="103" fill="#cbd5e1" font-size="12">incremental artifact chunks</text>
+
+    <!-- 03 LLM Research -->
+    <text x="570" y="47"  fill="#e2e8f0" font-size="17" font-weight="700">03 LLM Research</text>
+    <text x="570" y="67"  fill="#fcd34d" font-size="12">multi-agent · multi_server</text>
+    <text x="570" y="85"  fill="#cbd5e1" font-size="12">parallel SSE · evaluator</text>
+    <text x="570" y="103" fill="#cbd5e1" font-size="12">CLI + Sinatra web client</text>
+
+    <!-- 04 Resubscribe -->
+    <text x="30"  y="167" fill="#e2e8f0" font-size="17" font-weight="700">04 Resubscribe</text>
+    <text x="30"  y="187" fill="#93c5fd" font-size="12">tasks/resubscribe</text>
+    <text x="30"  y="205" fill="#cbd5e1" font-size="12">mid-stream join · snapshot</text>
+    <text x="30"  y="223" fill="#cbd5e1" font-size="12">concurrent subscribers</text>
+
+    <!-- 05 Cancellation -->
+    <text x="300" y="167" fill="#e2e8f0" font-size="17" font-weight="700">05 Cancellation</text>
+    <text x="300" y="187" fill="#fcd34d" font-size="12">tasks/cancel</text>
+    <text x="300" y="205" fill="#cbd5e1" font-size="12">concurrent tasks · lifecycle</text>
+    <text x="300" y="223" fill="#cbd5e1" font-size="12">cooperative cancellation</text>
+
+    <!-- 06 Push Notifications -->
+    <text x="570" y="167" fill="#e2e8f0" font-size="17" font-weight="700">06 Push Notifications</text>
+    <text x="570" y="187" fill="#86efac" font-size="12">pushNotification/set/get/del</text>
+    <text x="570" y="205" fill="#cbd5e1" font-size="12">webhook delivery · PushSender</text>
+    <text x="570" y="223" fill="#cbd5e1" font-size="12">out-of-band events</text>
+
+    <!-- 07 Agent Chaining -->
+    <text x="30"  y="287" fill="#e2e8f0" font-size="17" font-weight="700">07 Agent Chaining</text>
+    <text x="30"  y="307" fill="#c4b5fd" font-size="12">A2A.client inside executor</text>
+    <text x="30"  y="325" fill="#cbd5e1" font-size="12">agent-to-agent delegation</text>
+    <text x="30"  y="343" fill="#cbd5e1" font-size="12">composable pipelines</text>
+
+    <!-- 08 Interrupted States -->
+    <text x="300" y="287" fill="#e2e8f0" font-size="17" font-weight="700">08 Interrupted States</text>
+    <text x="300" y="307" fill="#fcd34d" font-size="12">input_required · auth_required</text>
+    <text x="300" y="325" fill="#cbd5e1" font-size="12">multi-turn conversations</text>
+    <text x="300" y="343" fill="#cbd5e1" font-size="12">message context_id threading</text>
+
+    <!-- 09 Multipart -->
+    <text x="570" y="287" fill="#e2e8f0" font-size="17" font-weight="700">09 Multipart</text>
+    <text x="570" y="307" fill="#5eead4" font-size="12">text · json · binary · url</text>
+    <text x="570" y="325" fill="#cbd5e1" font-size="12">Part predicates · base64</text>
+    <text x="570" y="343" fill="#cbd5e1" font-size="12">multi-type artifact</text>
+
+    <!-- 10 Auth Headers -->
+    <text x="30"  y="407" fill="#e2e8f0" font-size="17" font-weight="700">10 Auth Headers</text>
+    <text x="30"  y="427" fill="#fda4af" font-size="12">A2A.client(headers:)</text>
+    <text x="30"  y="445" fill="#cbd5e1" font-size="12">Bearer token middleware</text>
+    <text x="30"  y="463" fill="#cbd5e1" font-size="12">Rack middleware composition</text>
+
+    <!-- 11 SQLite Storage -->
+    <text x="300" y="407" fill="#e2e8f0" font-size="17" font-weight="700">11 SQLite Storage</text>
+    <text x="300" y="427" fill="#c4b5fd" font-size="12">Storage::Base injection</text>
+    <text x="300" y="445" fill="#cbd5e1" font-size="12">WAL persistence · Brewfile</text>
+    <text x="300" y="463" fill="#cbd5e1" font-size="12">cross-restart task survival</text>
   </g>
 </svg>
 
@@ -56,7 +116,8 @@ 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 launcher starts the demo server on `http://localhost:9292`, waits for it to accept connections, runs the demo client, and then shuts the server down.
@@ -68,25 +129,35 @@ bundle exec ruby examples/01_basic_usage/server.rb
 bundle exec ruby examples/01_basic_usage/client.rb
 ```
 
-## Demo-specific dependencies
+Some demos (`03_llm_research`, `11_sqlite_storage`) have custom `run` scripts that manage a more complex lifecycle; the top-level launcher detects and delegates to them automatically.
 
-The basic and streaming demos use only the gem and its normal development setup. The LLM research demo intentionally keeps its LLM and web UI dependencies out of the gem runtime dependency list. Install the demo-specific gems before running it:
+## Demo-specific dependencies
 
-```bash
-bundle add ruby_llm async-http-faraday sinatra
-```
+Most demos run with the gem's standard development setup (`bundle install`).
 
-Then set API keys:
+**Demo 03 — LLM Research** requires LLM provider API keys and additional gems not in the gem's runtime dependency list:
 
 ```bash
+bundle add ruby_llm async-http-faraday sinatra
 export ANTHROPIC_API_KEY=your_key_here
 export OPENAI_API_KEY=your_key_here
+bundle exec ruby examples/run 03_llm_research
 ```
 
+**Demo 11 — SQLite Storage** has its own `Gemfile` and `Brewfile`. The `run` script installs the sqlite3 binary (via Homebrew on macOS) and runs `bundle install` with the local Gemfile before starting the server. No manual setup is required.
+
 ## Demo index
 
-| Demo | Command | Documentation |
-|---|---|---|
-| Basic Usage | `bundle exec ruby examples/run 01_basic_usage` | [Basic Usage](basic-usage.md) |
-| Streaming | `bundle exec ruby examples/run 02_streaming` | [Streaming](streaming.md) |
-| Multi-Agent LLM Research | `bundle exec ruby examples/run 03_llm_research` | [Multi-Agent LLM Research](llm-research.md) |
+| # | Demo | Run command | Documentation |
+|---|---|---|---|
+| 01 | Basic Usage | `examples/run 01_basic_usage` | [Basic Usage](basic-usage.md) |
+| 02 | Streaming | `examples/run 02_streaming` | [Streaming](streaming.md) |
+| 03 | LLM Research | `examples/run 03_llm_research` | [LLM Research](llm-research.md) |
+| 04 | Resubscribe | `examples/run 04_resubscribe` | [Resubscribe](resubscribe.md) |
+| 05 | Cancellation | `examples/run 05_cancellation` | [Cancellation](cancellation.md) |
+| 06 | Push Notifications | `examples/run 06_push_notifications` | [Push Notifications](push-notifications.md) |
+| 07 | Agent Chaining | `examples/run 07_agent_chaining` | [Agent Chaining](agent-chaining.md) |
+| 08 | Interrupted States | `examples/run 08_interrupted_states` | [Interrupted States](interrupted-states.md) |
+| 09 | Multipart Artifacts | `examples/run 09_multipart` | [Multipart](multipart.md) |
+| 10 | Auth Headers | `examples/run 10_auth_headers` | [Auth Headers](auth-headers.md) |
+| 11 | SQLite Storage | `examples/run 11_sqlite_storage` | [SQLite Storage](sqlite-storage.md) |