simple_a2a 0.1.0 → 0.3.0

data/docs/examples/interrupted-states.md

@@ -0,0 +1,114 @@
+# 08 Interrupted States
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 08_interrupted_states
+```
+
+**What it shows:** `input_required` and `auth_required` — the two interrupted task states — with multi-turn conversations threaded by `message.context_id`.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/08_interrupted_states/server.rb` | Two agents: `OrderAgent` (`input_required`) and `VaultAgent` (`auth_required`) |
+| `examples/08_interrupted_states/client.rb` | Drives two separate multi-turn conversations, each as a sequence of `tasks/send` calls |
+
+---
+
+## The scenario
+
+Two independent conversation threads run in sequence:
+
+**Thread A — `input_required`**
+
+1. Client sends "start order" → server returns `input_required` asking "what would you like?"
+2. Client sends "one large pizza" with the same `context_id` → server returns `completed` with the order confirmation.
+
+**Thread B — `auth_required`**
+
+1. Client sends "get secret" → server returns `auth_required`.
+2. Client sends wrong token → server stays in `auth_required` (repeated challenge).
+3. Client sends correct token → server returns `completed` with the protected data.
+
+---
+
+## Key concept — `context_id`
+
+Each conversational turn is a separate `tasks/send` call. The server uses `message.context_id` to look up the in-progress conversation state:
+
+```ruby
+# Client — build a message with an explicit context_id
+def msg(text, context_id:)
+  A2A::Models::Message.new(
+    role:       A2A::Models::Types::Role::USER,
+    parts:      [A2A::Models::Part.text(text)],
+    context_id: context_id
+  )
+end
+
+context = SecureRandom.uuid
+
+# Turn 1
+task1 = client.send_task(message: msg("start order", context_id: context))
+# task1.status.state => "input_required"
+
+# Turn 2
+task2 = client.send_task(message: msg("one large pizza", context_id: context))
+# task2.status.state => "completed"
+```
+
+---
+
+## Server — executor state
+
+Each executor keeps a mutex-protected hash keyed by `context_id`:
+
+```ruby
+class OrderExecutor < A2A::Server::AgentExecutor
+  def initialize
+    @pending = {}
+    @mutex   = Mutex.new
+  end
+
+  def call(ctx)
+    cid = ctx.message.context_id
+
+    if @mutex.synchronize { @pending[cid] }
+      # Turn 2 — complete the order
+      item = ctx.message.text_content.strip
+      @mutex.synchronize { @pending.delete(cid) }
+      ctx.task.complete!(artifacts: [
+        A2A::Models::Artifact.new(
+          parts: [A2A::Models::Part.text("Order placed: #{item}")]
+        )
+      ])
+    else
+      # Turn 1 — ask what they want
+      @mutex.synchronize { @pending[cid] = true }
+      ctx.task.require_input!(message: A2A::Models::Message.new(
+        role:  A2A::Models::Types::Role::AGENT,
+        parts: [A2A::Models::Part.text("What would you like to order?")]
+      ))
+    end
+  end
+end
+```
+
+The `VaultAgent` follows the same pattern with `require_auth!` and a token check that stays in `auth_required` on a wrong value, demonstrating that the interrupted state is non-terminal and resumable.
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| `input_required` state | Task transitions to an interrupted state; `status.message` carries the question |
+| `auth_required` state | Task blocks until the client provides valid credentials |
+| Multi-turn conversations | Each follow-up is a new `tasks/send` carrying the same `context_id` |
+| `Message.context_id` | Executor uses the message's `contextId` field to thread state across separate task calls |
+| `TaskState` interrupted vs terminal | `input_required` and `auth_required` are non-terminal; the task can still complete |
+| Rejection on bad auth | VaultAgent stays in `auth_required` on a wrong token, demonstrating repeated challenge |

data/docs/examples/multipart.md

@@ -0,0 +1,103 @@
+# 09 Multipart Artifacts
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 09_multipart
+```
+
+**What it shows:** a single artifact carrying all four `Part` types — `text`, `json`, `binary`, and `url` — and how the client uses predicate methods to dispatch on part type.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/09_multipart/server.rb` | `ReportExecutor` builds one four-part artifact covering every `Part` constructor |
+| `examples/09_multipart/client.rb` | Iterates artifact parts; uses `text?`, `json?`, `raw?`, `url?` to process each type |
+
+---
+
+## The four Part types
+
+| Constructor | Transport format | Client accessor |
+|---|---|---|
+| `Part.text(str, media_type:)` | Plain string | `part.text` |
+| `Part.json(hash, filename:)` | JSON object | `part.data` |
+| `Part.binary(bytes, media_type:, filename:)` | Base64-encoded string | `part.decoded_bytes` |
+| `Part.from_url(url, media_type:, filename:)` | URL string, no inline content | `part.url` |
+
+---
+
+## Server — `ReportExecutor`
+
+```ruby
+def call(ctx)
+  topic = ctx.message.text_content.strip
+
+  summary = A2A::Models::Part.text(<<~TEXT, media_type: "text/plain")
+    Report on: #{topic}
+    Generated at #{Time.now.utc.iso8601}
+  TEXT
+
+  metadata = A2A::Models::Part.json(
+    { "topic" => topic, "word_count" => topic.split.length, "confidence" => 0.92 },
+    filename: "metadata.json"
+  )
+
+  csv_bytes = build_csv(topic).b
+  csv_part  = A2A::Models::Part.binary(
+    csv_bytes, media_type: "text/csv", filename: "term_scores.csv"
+  )
+
+  url_part = A2A::Models::Part.from_url(
+    "https://en.wikipedia.org/wiki/Special:Search?search=#{URI.encode_uri_component(topic)}",
+    media_type: "text/html",
+    filename:   "reference.html"
+  )
+
+  ctx.task.complete!(artifacts: [
+    A2A::Models::Artifact.new(name: "report", parts: [summary, metadata, csv_part, url_part])
+  ])
+end
+```
+
+---
+
+## Client — type-safe dispatch
+
+```ruby
+artifact.parts.each do |part|
+  if part.text?
+    puts part.text
+
+  elsif part.json?
+    puts JSON.pretty_generate(part.data)
+
+  elsif part.raw?
+    bytes = part.decoded_bytes
+    puts "#{bytes.bytesize} bytes (#{part.media_type})"
+    puts bytes.force_encoding("UTF-8")
+
+  elsif part.url?
+    puts part.url
+  end
+end
+```
+
+The predicates `text?`, `json?`, `raw?`, and `url?` are mutually exclusive. `decoded_bytes` reverses the base64 encoding that the transport layer applies to binary parts.
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| `Part.text` | Plain prose with `media_type: "text/plain"` |
+| `Part.json` | Structured data as a Ruby Hash; serialized as a JSON object in the artifact |
+| `Part.binary` | Raw bytes base64-encoded for transport; `decoded_bytes` restores the original |
+| `Part.from_url` | URL reference with `media_type` and `filename`; no content is inlined |
+| `Part` predicates | `text?`, `json?`, `raw?`, `url?` allow type-safe dispatch on the receiving end |
+| Multi-part `Artifact` | One artifact contains all four parts; clients can select the representation they need |
+| `Artifact.name` | Named artifact (`"report"`) for client-side identification |

data/docs/examples/push-notifications.md

@@ -0,0 +1,117 @@
+# 06 Push Notifications
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 06_push_notifications
+```
+
+**What it shows:** the full push notification CRUD cycle — registering a webhook, confirming it, receiving out-of-band task events, then deleting the config.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/06_push_notifications/server.rb` | `PushExecutor` that delivers `TaskStatusUpdateEvent` payloads to the registered webhook after each step |
+| `examples/06_push_notifications/client.rb` | Runs a local WEBrick webhook receiver on port 9293, submits a task, and exercises all four push-notification RPC methods |
+
+---
+
+## The scenario
+
+The client holds no persistent SSE connection. Instead:
+
+1. It starts a local HTTP receiver on port 9293 backed by a `Queue`.
+2. It submits a task via `tasks/send` (synchronous — gets back the initial task object).
+3. It registers the webhook URL via `tasks/pushNotification/set`.
+4. The server `PushExecutor` runs its work steps; after each step it looks up the push config and delivers a `TaskStatusUpdateEvent` to the webhook.
+5. The client's `Queue` collects payloads; the main thread waits until it receives the final `completed` event.
+6. The client confirms the config exists (`tasks/pushNotification/get`), lists all configs (`tasks/pushNotification/list`), then removes the config (`tasks/pushNotification/delete`).
+
+---
+
+## Server design
+
+`PushExecutor` is initialized with a shared `PushSender` and `PushConfigStore`. After each work step it delivers an event:
+
+```ruby
+class PushExecutor < A2A::Server::AgentExecutor
+  def initialize(push_sender:, push_config_store:)
+    @push_sender       = push_sender
+    @push_config_store = push_config_store
+  end
+
+  def call(ctx)
+    ctx.task.start!
+    deliver(ctx)
+
+    3.times do |i|
+      sleep 1
+      ctx.emit_artifact(...)
+      deliver(ctx)
+    end
+
+    ctx.task.complete!
+    deliver(ctx)
+  end
+
+  private
+
+  def deliver(ctx)
+    config = @push_config_store.get(ctx.task.id)
+    return unless config
+    event = A2A::Models::TaskStatusUpdateEvent.new(
+      task_id: ctx.task.id, status: ctx.task.status, final: ctx.task.terminal?
+    )
+    @push_sender.deliver(config, event)
+  end
+end
+```
+
+The same `push_config_store` instance is passed to both the executor and `A2A.server(push_config_store:)`, so the server's built-in RPC handlers and the executor share one store.
+
+---
+
+## Client design
+
+WEBrick in a background thread writes received payloads into a `Queue`; the main thread reads from it:
+
+```ruby
+queue = Queue.new
+
+server = WEBrick::HTTPServer.new(Port: 9293, Logger: ..., AccessLog: [])
+server.mount_proc("/webhook") do |req, res|
+  queue.push(JSON.parse(req.body))
+  res.status = 200
+end
+Thread.new { server.start }
+
+# Register the webhook
+client.rpc_call("tasks/pushNotification/set", {
+  "id"     => task.id,
+  "config" => { "webhookUrl" => "http://localhost:9293/webhook" }
+})
+
+# Wait for the final push
+loop do
+  payload = queue.pop
+  break if payload.dig("status", "state") == "completed"
+end
+```
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| `tasks/pushNotification/set` | Client registers a `PushNotificationConfig` containing a webhook URL |
+| `tasks/pushNotification/get` | Client confirms the config is stored by retrieving it by task ID |
+| `tasks/pushNotification/list` | Client lists all registered push configs on the server |
+| `tasks/pushNotification/delete` | Client removes the config; list confirms zero configs remain |
+| `PushNotificationConfig` model | `webhookUrl` and optional `authenticationInfo` fields |
+| `PushSender` | Server delivers `TaskStatusUpdateEvent` payloads as HTTP POSTs to the webhook URL |
+| `AgentCapabilities.push_notifications` | `true` in the agent card; server rejects push RPC calls if `false` |
+| Out-of-band delivery | Client receives progress updates without maintaining any persistent connection |

data/docs/examples/resubscribe.md

@@ -0,0 +1,129 @@
+# 04 Resubscribe
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 04_resubscribe
+```
+
+**What it shows:** two independent SSE subscribers watching the same running task — one started with `tasks/sendSubscribe`, the other attached mid-stream with `tasks/resubscribe`.
+
+---
+
+## The scenario
+
+A five-step analysis pipeline runs for ~6 seconds. Subscriber 1 starts the task and begins receiving events immediately. As soon as it has the task ID, Subscriber 2 calls `tasks/resubscribe`. Subscriber 2's **first event is the current Task snapshot** — the live state of the task at the moment it joined — and it then receives all remaining events just like Subscriber 1.
+
+This demonstrates three protocol guarantees from the A2A specification:
+
+1. **Snapshot on join** — `tasks/resubscribe` always delivers the current Task object as its first SSE event, so late-joining clients never miss the task's current state.
+2. **Independent fan-out** — each subscriber has its own event queue; one slow or disconnecting subscriber does not affect the other.
+3. **Single completion** — the task completes once; both streams close cleanly when the executor emits its final status event.
+
+---
+
+## Expected output
+
+```
+=== Agent Card ===
+  Name:        AnalysisAgent
+  Description: Multi-step analysis pipeline — demonstrates tasks/resubscribe
+  Streaming:   true
+
+[subscriber-1] tasks/sendSubscribe (new task)       [subscriber-2] tasks/resubscribe (join mid-stream)
+────────────────────────────────────────────────────────────────────────────────────
+[subscriber-1] status: working
+[subscriber-2] (resubscribing to task c29189f8…)
+[subscriber-2] (snapshot) state=working, steps so far: 0
+[subscriber-1] Step 1/5: Collecting data from sources
+[subscriber-2] Step 1/5: Collecting data from sources
+[subscriber-1] Step 2/5: Filtering and normalising records
+[subscriber-2] Step 2/5: Filtering and normalising records
+...
+[subscriber-1] status (final): completed
+[subscriber-2] status (final): completed
+
+=== Summary ===
+  Subscriber 1 — events received : 7
+  Subscriber 1 — artifact steps  : 5
+
+  Subscriber 2 — events received : 7
+  Subscriber 2 — task snapshot   : yes
+  Subscriber 2 — artifact steps  : 5
+  Subscriber 2 — joined at step  : 1 of 5
+
+  Both streams terminated cleanly: true
+```
+
+---
+
+## How it works
+
+### Server — `AnalysisExecutor`
+
+A straightforward streaming executor. Emits one `TaskArtifactUpdateEvent` per step with a 1.2-second pause between steps, giving the client time to resubscribe mid-stream.
+
+```ruby
+class AnalysisExecutor < A2A::Server::AgentExecutor
+  STEPS = [
+    "Collecting data from sources",
+    "Filtering and normalising records",
+    "Running statistical analysis",
+    "Detecting anomalies",
+    "Generating final report"
+  ].freeze
+
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status
+
+    STEPS.each_with_index do |description, i|
+      sleep 1.2
+      ctx.emit_artifact(A2A::Models::Artifact.new(
+        index:      i,
+        parts:      [A2A::Models::Part.text("Step #{i + 1}/#{STEPS.length}: #{description}")],
+        last_chunk: true
+      ), last_chunk: true)
+    end
+
+    ctx.task.complete!
+    ctx.emit_status(final: true)
+  end
+end
+```
+
+### Client — concurrent subscribers via `Async`
+
+Both subscribers run inside a single `Async` reactor. Subscriber 1 runs in a background async task so it doesn't block; once it captures the task ID from the first status event, the main fiber calls `resubscribe` synchronously.
+
+```ruby
+Async do |reactor|
+  captured_task_id = nil
+
+  # Subscriber 1 — starts the task
+  sub1_task = reactor.async do
+    A2A.sse_client(url: URL).send_subscribe(message: msg) do |event|
+      captured_task_id ||= event.task_id if event.respond_to?(:task_id)
+      # … print event …
+    end
+  end
+
+  # Wait for the task ID, then attach Subscriber 2
+  loop { break if captured_task_id; reactor.sleep(0.05) }
+
+  A2A.sse_client(url: URL).resubscribe(task_id: captured_task_id) do |event|
+    case event
+    when Hash                                    # Task snapshot — first event only
+      puts "(snapshot) state=#{event.dig('status', 'state')}"
+    when A2A::Models::TaskStatusUpdateEvent, A2A::Models::TaskArtifactUpdateEvent
+      # … print event …
+    end
+  end
+
+  sub1_task.wait
+end
+```
+
+### Under the hood — `TaskBroadcast`
+
+When `handle_send_subscribe` creates the task, it also creates a `TaskBroadcast` and registers it in the `BroadcastRegistry` under the task ID. Each SSE subscriber — whether the original or a resubscriber — gets its own `RactorQueue` from `broadcast.subscribe`. The executor calls `ctx.emit_status` and `ctx.emit_artifact`, which call `broadcast.publish`, which calls `async_push` on every subscriber queue. A pump loop in each SSE handler calls `async_pop` and writes SSE frames to the HTTP body. When the executor finishes, `broadcast.close` pushes the `DONE` sentinel to all queues and the pump loops exit cleanly.

data/docs/examples/sqlite-storage.md

@@ -0,0 +1,131 @@
+# 11 SQLite3 Persistent Storage
+
+**Run it:**
+
+```bash
+bundle exec ruby examples/run 11_sqlite_storage
+```
+
+**What it shows:** replacing the default in-memory store with a custom `Storage::Base` subclass backed by SQLite3, proving that tasks survive a full server restart.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/11_sqlite_storage/server.rb` | `SqliteStorage < A2A::Storage::Base` and the `PersistentEchoAgent` server |
+| `examples/11_sqlite_storage/client.rb` | `populate` phase (send tasks, save IDs) and `verify` phase (fetch tasks after restart) |
+| `examples/11_sqlite_storage/run` | Two-phase lifecycle: populate → stop → restart → verify → cleanup |
+| `examples/11_sqlite_storage/Gemfile` | Extends the project gemspec + adds `sqlite3` |
+| `examples/11_sqlite_storage/Brewfile` | Declares the `sqlite3` binary dependency for Homebrew |
+
+---
+
+## Dependencies
+
+This demo has its own `Gemfile` and `Brewfile`. The `run` script handles setup before spawning anything:
+
+1. **Binary check** — verifies `sqlite3` is on `$PATH`; on macOS runs `brew bundle install --file=Brewfile` if it is not. Other platforms must provide the binary.
+2. **Gem install** — runs `bundle install` with the local `Gemfile`, which uses `gemspec path: "../../"` to pull in all project dependencies plus `sqlite3`.
+
+Once setup completes, `server.rb` can simply `require "sqlite3"` with no inline install logic.
+
+---
+
+## The two-phase demo
+
+**Phase 1 — populate**
+
+The server starts with an empty database. The client sends three tasks (alpha, beta, gamma) and writes their IDs to a temp JSON file, then the server stops.
+
+**Phase 2 — verify**
+
+The server restarts pointing at the same database file. At startup it prints the existing task count (`existing tasks in DB: 3`), confirming the data survived. The client reads the saved IDs, fetches each task from the freshly booted server, and asserts all three are present and `completed`.
+
+---
+
+## `SqliteStorage` implementation
+
+`SqliteStorage` subclasses `A2A::Storage::Base` and implements all five required methods:
+
+```ruby
+class SqliteStorage < A2A::Storage::Base
+  def initialize(path)
+    @db    = SQLite3::Database.new(path)
+    @mutex = Mutex.new
+    @db.execute("PRAGMA journal_mode=WAL")
+    @db.execute("PRAGMA busy_timeout=5000")
+    setup_schema
+  end
+
+  def save(task)
+    @mutex.synchronize do
+      now = Time.now.iso8601
+      @db.execute(
+        "INSERT INTO tasks (id, data, created_at, updated_at) VALUES (?, ?, ?, ?) " \
+        "ON CONFLICT(id) DO UPDATE SET data=excluded.data, updated_at=excluded.updated_at",
+        [task.id, task.to_h.to_json, now, now]
+      )
+    end
+    task
+  end
+
+  def find(id)
+    row = @mutex.synchronize { @db.get_first_row("SELECT data FROM tasks WHERE id=?", [id]) }
+    return nil unless row
+    A2A::Models::Task.from_hash(JSON.parse(row[0]))
+  end
+
+  def find!(id)
+    find(id) or raise A2A::TaskNotFoundError, "Task #{id} not found"
+  end
+
+  def list
+    rows = @mutex.synchronize { @db.execute("SELECT data FROM tasks ORDER BY rowid") }
+    rows.map { |row| A2A::Models::Task.from_hash(JSON.parse(row[0])) }
+  end
+
+  def delete(id)
+    @mutex.synchronize { @db.execute("DELETE FROM tasks WHERE id=?", [id]) }
+  end
+end
+```
+
+Tasks are stored as JSON blobs. `from_hash` reconstructs the full `Task` object including nested `TaskStatus`, `Artifact`, and `Part` models.
+
+WAL mode allows concurrent readers while a write is in progress — important when multiple fibers are saving and fetching tasks simultaneously in a Falcon server.
+
+---
+
+## Injecting the storage
+
+The storage instance is passed to `A2A.server` via the `storage:` keyword:
+
+```ruby
+storage = SqliteStorage.new(db_path)
+A2A.server(agent_card: card, executor: EchoExecutor.new, storage: storage).run
+```
+
+No other library configuration is needed. The server's built-in RPC handlers (`tasks/get`, `tasks/list`, `tasks/cancel`, etc.) all use the injected store.
+
+---
+
+## Protocol coverage
+
+| Spec section | What the demo shows |
+|---|---|
+| `Storage::Base` injection | `A2A.server(storage:)` accepts any `Storage::Base` subclass — no library changes needed |
+| `SqliteStorage#save` | Tasks serialized to JSON and upserted via `ON CONFLICT DO UPDATE` |
+| `SqliteStorage#find!` | Task fetched by ID across process boundaries; raises `TaskNotFoundError` if missing |
+| `SqliteStorage#list` | All stored tasks returned in insertion order |
+| `SqliteStorage#size` | Task count reported at server startup to confirm DB contents |
+| Cross-restart persistence | Tasks created in server process 1 are visible to server process 2 via the shared DB file |
+| WAL mode concurrency | `PRAGMA journal_mode=WAL` allows concurrent readers during writes |
+| `Brewfile` / `Gemfile` pattern | Per-demo dependency files keep application code free of setup logic |
+
+---
+
+## Related guide
+
+See [Custom Storage](../guides/custom-storage.md) for a detailed walkthrough of the `Storage::Base` interface and adapter patterns for other databases.

data/docs/examples/streaming.md

@@ -37,10 +37,7 @@ def call(ctx)
     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
+      parts: [A2A::Models::Part.text(text)]
     )
 
     ctx.emit_artifact(artifact, append: i > 0, last_chunk: i == WORDS.length - 1)

data/docs/guides/push-notifications.md

@@ -80,7 +80,10 @@ A JWT is generated and sent as `Authorization: Bearer <token>`. The token payloa
 ```
 
 ```ruby
-auth = A2A::Models::AuthenticationInfo.new(scheme: "bearer")
+auth = A2A::Models::AuthenticationInfo.new(
+  scheme: "bearer",
+  value:  ""   # not used for JWT; PushSender generates the token from the private key
+)
 ```
 
 ### Static token

data/docs/guides/streaming.md

@@ -16,10 +16,7 @@ class StreamingExecutor < A2A::Server::AgentExecutor
     ["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
+        parts: [A2A::Models::Part.text(chunk)]
       )
       ctx.emit_artifact(artifact, append: i > 0, last_chunk: last)
     end
@@ -64,6 +61,38 @@ The block is called for each parsed SSE event. Unrecognized event types yield a
 
 ---
 
+---
+
+## Resubscribing to an existing task
+
+`tasks/resubscribe` lets a client attach a new SSE stream to a task that is already running — useful when a connection drops and the client needs to reconnect without re-sending the original message.
+
+```ruby
+client = A2A.sse_client(url: "http://localhost:9292")
+
+# The first event yielded is the current Task snapshot (a Hash, no `type` field).
+# Subsequent events are the live stream from the executor.
+client.resubscribe(task_id: "existing-task-id") do |event|
+  case event
+  when Hash
+    puts "reconnected — current state: #{event['status']['state']}"
+  when A2A::Models::TaskStatusUpdateEvent
+    puts "[status] #{event.status.state}  final=#{event.final}"
+  when A2A::Models::TaskArtifactUpdateEvent
+    print event.artifact.parts.map(&:text).join
+  end
+end
+```
+
+`resubscribe` raises (server returns `UnsupportedOperationError`) if:
+- The task ID does not exist (`TaskNotFoundError`)
+- The task is already in a terminal state
+- The task was not started with `tasks/sendSubscribe` (not in the broadcast registry)
+
+Multiple clients may resubscribe to the same task concurrently — each gets an independent event queue backed by `RactorQueue`.
+
+---
+
 ## AgentCard declaration
 
 Advertise streaming support in your AgentCard:
@@ -72,4 +101,4 @@ Advertise streaming support in your AgentCard:
 capabilities = A2A::Models::AgentCapabilities.new(streaming: true)
 ```
 
-Clients can check `card.capabilities.streaming` before using `send_subscribe`.
+Clients can check `card.capabilities.streaming` before using `send_subscribe` or `resubscribe`.