simple_a2a 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8200755c9d568b3b1161815a2dfd8df190efe773ae946a00fafcfddd25b1ca4e
-  data.tar.gz: a5f112a8138f111d137b1a443c674a309c0ad98c5c6f5b8473e4c5d3af42d316
+  metadata.gz: 69d7ae29ed8960745bbeaebfd8368cdd52162d81f5faa8779d9d5ffc00634e21
+  data.tar.gz: 1bc2957a22ec2de785da814cb8d87f1a776562f9fdb7fed7ad26eb060482d3a4
 SHA512:
-  metadata.gz: 39509e60e4665ca244831830f6b9c5cb4e3de384c98c7e5d5ae74ab15bdce5c06fb942fb85a6738a11e2d6080f8ab2c3c6334d0be02f58e04bd1f364a9df1231
-  data.tar.gz: d6c85963a895435cffa1b3ec28ad7bc7506d168274ae2281b4e7c590ff0d4b48387cb97a4f249aaf7df01621ade3b8aeaf7e3de14e2e35cfad42625600084635
+  metadata.gz: 3fa6b8af3c6bcdb450c05263add6687fd3aac6bb338d80d17d1775715fea95419290f7ebe1ec6fc4b436ee5594a68276fa91d4a9edfc47f4d8084ea3d5a12092
+  data.tar.gz: 64dacdabd05f8347418e7fdb63609d9f6750bb7c4eb4377f69cae20e3e9d52a994df7e52f104d4d1a7cddb696914e5cd8de0d5998d07dfbbc73181a72a385a8e

data/Rakefile

@@ -11,3 +11,82 @@ Minitest::TestTask.create do |t|
 end
 
 task default: :test
+
+desc 'Check code style with RuboCop'
+task :rubocop do
+  sh 'bundle exec rubocop'
+end
+
+desc 'Auto-correct RuboCop offenses'
+task :rubocop_fix do
+  sh 'bundle exec rubocop -a'
+end
+
+desc 'Check code complexity with Flog (warn >=20, fail >=50)'
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb'))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
+task :quality do
+  results = {}
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: Tests + Coverage'
+  puts '=' * 60
+  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: RuboCop'
+  puts '=' * 60
+  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Gate: Flog Complexity'
+  puts '=' * 60
+  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts 'Quality Summary'
+  puts '=' * 60
+  results.each do |gate, status|
+    icon = status == :pass ? 'PASS' : 'FAIL'
+    puts "  [#{icon}] #{gate}"
+  end
+  puts '=' * 60
+
+  abort "\nQuality gate failed" if results.values.any?(:fail)
+  puts "\nAll quality gates passed."
+end

data/examples/01_basic_usage/client.rb

@@ -15,13 +15,15 @@ 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
+puts <<~HEREDOC
+  === Agent Card ===
+    Name:        #{card.name}
+    Version:     #{card.version}
+    Description: #{card.description}
+    Skills:      #{card.skills.map(&:name).join(', ')}
+
+HEREDOC
 
 # ---------------------------------------------------------------------------
 # 2. Send a few tasks
@@ -57,12 +59,14 @@ 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
+puts <<~HEREDOC
+  === Retrieve Task ===
+    id:    #{retrieved.id}
+    state: #{retrieved.status.state}
+    reply: #{retrieved.artifacts.first&.parts&.first&.text.inspect}
+
+HEREDOC
 
 # ---------------------------------------------------------------------------
 # 5. Cancel a non-existent task (demonstrates error handling)

data/examples/01_basic_usage/server.rb

@@ -50,8 +50,10 @@ card = A2A::Models::AgentCard.new(
 # ---------------------------------------------------------------------------
 # Start the server (blocks; Ctrl-C to stop).
 # ---------------------------------------------------------------------------
-puts "Starting BasicAgent on http://localhost:9292"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting BasicAgent on http://localhost:9292
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(agent_card: card, executor: BasicExecutor.new).run

data/examples/02_streaming/client.rb

@@ -16,12 +16,14 @@ client = A2A.sse_client(url: URL)
 # 1. Confirm the agent advertises streaming support
 # ---------------------------------------------------------------------------
 card = client.agent_card
-puts "=== Agent Card ==="
-puts "  Name:        #{card.name}"
-puts "  Description: #{card.description}"
-puts "  Streaming:   #{card.capabilities&.streaming}"
-puts "  Source:      https://lamplight.guide/blog/the-god-particle/"
-puts
+puts <<~HEREDOC
+  === Agent Card ===
+    Name:        #{card.name}
+    Description: #{card.description}
+    Streaming:   #{card.capabilities&.streaming}
+    Source:      https://lamplight.guide/blog/the-god-particle/
+
+HEREDOC
 
 # ---------------------------------------------------------------------------
 # 2. Subscribe and print words as they stream in
@@ -62,9 +64,11 @@ end
 elapsed = start_time ? (Time.now - start_time) : 0
 wpm     = elapsed > 0 ? (word_count / (elapsed / 60.0)).round : 0
 
-puts
-puts "=== Summary ==="
-puts "  Words received  : #{word_count}"
-puts "  Events received : #{event_count}"
-puts "  Elapsed         : #{elapsed.round(1)}s — #{wpm} WPM effective"
-puts "  Status          : #{interrupted ? "interrupted" : "completed"}"
+puts <<~HEREDOC
+
+  === Summary ===
+    Words received  : #{word_count}
+    Events received : #{event_count}
+    Elapsed         : #{elapsed.round(1)}s — #{wpm} WPM effective
+    Status          : #{interrupted ? "interrupted" : "completed"}
+HEREDOC

data/examples/02_streaming/server.rb

@@ -169,9 +169,11 @@ card = A2A::Models::AgentCard.new(
   ]
 )
 
-puts "Starting StreamingAgent on http://localhost:9292"
-puts "Streaming #{StreamingExecutor::WORDS.length} words at 600 WPM (~#{(StreamingExecutor::WORDS.length / 600.0).ceil} min)"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting StreamingAgent on http://localhost:9292
+  Streaming #{StreamingExecutor::WORDS.length} words at 600 WPM (~#{(StreamingExecutor::WORDS.length / 600.0).ceil} min)
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(agent_card: card, executor: StreamingExecutor.new).run

data/examples/03_llm_research/client.rb

@@ -17,9 +17,11 @@ topic = ARGV.first || "research all shortcomings and defects and criticisms of t
 
 def banner(text)
   bar = "─" * (text.length + 4)
-  puts "┌#{bar}┐"
-  puts "│  #{text}  │"
-  puts "└#{bar}┘"
+  puts <<~HEREDOC
+    ┌#{bar}┐
+    │  #{text}  │
+    └#{bar}┘
+  HEREDOC
 end
 
 def collect_streaming_response(url, topic)
@@ -40,10 +42,12 @@ end
 # 1. Research phase — query both agents in parallel
 # ---------------------------------------------------------------------------
 banner "Research Phase: \"#{topic}\""
-puts
-puts "Querying Anthropic (claude-sonnet-4-6) and OpenAI (gpt-5.4) in parallel…"
-puts "This may take several minutes for complex topics."
-puts
+puts <<~HEREDOC
+
+  Querying Anthropic (claude-sonnet-4-6) and OpenAI (gpt-5.4) in parallel…
+  This may take several minutes for complex topics.
+
+HEREDOC
 
 anthropic_text = nil
 openai_text    = nil

data/examples/03_llm_research/server.rb

@@ -186,12 +186,14 @@ evaluator_card = A2A::Models::AgentCard.new(
 # ---------------------------------------------------------------------------
 # Start multi-agent server
 # ---------------------------------------------------------------------------
-puts "Starting multi-agent research server on http://localhost:9292"
-puts "  /anthropic  → #{AnthropicResearchExecutor::MODEL}"
-puts "  /openai     → #{OpenAIResearchExecutor::MODEL}"
-puts "  /evaluator  → #{EvaluatorExecutor::MODEL} (evaluator)"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting multi-agent research server on http://localhost:9292
+    /anthropic  → #{AnthropicResearchExecutor::MODEL}
+    /openai     → #{OpenAIResearchExecutor::MODEL}
+    /evaluator  → #{EvaluatorExecutor::MODEL} (evaluator)
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.multi_server(
   agents: {

data/examples/04_resubscribe/client.rb

@@ -43,11 +43,13 @@ end
 base = A2A.client(url: URL)
 card = base.agent_card
 
-puts "=== Agent Card ==="
-puts "  Name:        #{card.name}"
-puts "  Description: #{card.description}"
-puts "  Streaming:   #{card.capabilities&.streaming}"
-puts
+puts <<~HEREDOC
+  === Agent Card ===
+    Name:        #{card.name}
+    Description: #{card.description}
+    Streaming:   #{card.capabilities&.streaming}
+
+HEREDOC
 
 abort "Agent does not advertise streaming support." unless card.capabilities&.streaming
 
@@ -118,23 +120,23 @@ end
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------
-divider
-puts
-puts "=== Summary ==="
-
-snapshot = sub2_events.find { |e| e.is_a?(Hash) && e.key?("status") }
+snapshot       = sub2_events.find { |e| e.is_a?(Hash) && e.key?("status") }
 sub2_artifacts = sub2_events.select { |e| e.is_a?(A2A::Models::TaskArtifactUpdateEvent) }
 sub1_artifacts = sub1_events.select { |e| e.is_a?(A2A::Models::TaskArtifactUpdateEvent) }
-
-puts "  Subscriber 1 — events received : #{sub1_events.length}"
-puts "  Subscriber 1 — artifact steps  : #{sub1_artifacts.length}"
-puts
-puts "  Subscriber 2 — events received : #{sub2_events.length}"
-puts "  Subscriber 2 — task snapshot   : #{snapshot ? 'yes' : 'no (unexpected)'}"
-puts "  Subscriber 2 — artifact steps  : #{sub2_artifacts.length}"
-puts "  Subscriber 2 — joined at step  : #{sub1_artifacts.length - sub2_artifacts.length + 1} of 5"
-puts
-puts "  Both streams terminated cleanly: #{
-  sub1_events.any? { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) && e.final? } &&
-  sub2_events.any? { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) && e.final? }
-}"
+divider
+puts <<~HEREDOC
+
+  === Summary ===
+    Subscriber 1 — events received : #{sub1_events.length}
+    Subscriber 1 — artifact steps  : #{sub1_artifacts.length}
+
+    Subscriber 2 — events received : #{sub2_events.length}
+    Subscriber 2 — task snapshot   : #{snapshot ? 'yes' : 'no (unexpected)'}
+    Subscriber 2 — artifact steps  : #{sub2_artifacts.length}
+    Subscriber 2 — joined at step  : #{sub1_artifacts.length - sub2_artifacts.length + 1} of 5
+
+    Both streams terminated cleanly: #{
+      sub1_events.any? { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) && e.final? } &&
+      sub2_events.any? { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) && e.final? }
+    }
+HEREDOC

data/examples/04_resubscribe/server.rb

@@ -67,9 +67,11 @@ card = A2A::Models::AgentCard.new(
 )
 
 total = AnalysisExecutor::STEPS.length * AnalysisExecutor::STEP_DELAY
-puts "Starting AnalysisAgent on http://localhost:9292"
-puts "Task runs #{AnalysisExecutor::STEPS.length} steps × #{AnalysisExecutor::STEP_DELAY}s = ~#{total.round(0).to_i}s per run"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting AnalysisAgent on http://localhost:9292
+  Task runs #{AnalysisExecutor::STEPS.length} steps × #{AnalysisExecutor::STEP_DELAY}s = ~#{total.round(0).to_i}s per run
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(agent_card: card, executor: AnalysisExecutor.new).run

data/examples/05_cancellation/client.rb

@@ -31,12 +31,14 @@ end
 # ---------------------------------------------------------------------------
 card = A2A.client(url: URL).agent_card
 
-puts
-puts "=== Agent Card ==="
-puts "  Name:         #{card.name}"
-puts "  Description:  #{card.description}"
-puts "  Streaming:    #{card.capabilities&.streaming}"
-puts
+puts <<~HEREDOC
+
+  === Agent Card ===
+    Name:         #{card.name}
+    Description:  #{card.description}
+    Streaming:    #{card.capabilities&.streaming}
+
+HEREDOC
 abort "Agent does not advertise streaming support." unless card.capabilities&.streaming
 divider
 
@@ -46,10 +48,12 @@ divider
 # A shared, mutex-protected hash lets the main thread see task IDs as soon
 # as the first status event arrives from each task.
 # ---------------------------------------------------------------------------
-puts
-puts "Starting tasks A, B, and C via tasks/sendSubscribe…"
-puts "(each would take 10 s; task B will be cancelled after #{CANCEL_SEC}s)"
-puts
+puts <<~HEREDOC
+
+  Starting tasks A, B, and C via tasks/sendSubscribe…
+  (each would take 10 s; task B will be cancelled after #{CANCEL_SEC}s)
+
+HEREDOC
 
 task_ids  = {}
 id_mutex  = Mutex.new
@@ -132,8 +136,6 @@ puts
 # ---------------------------------------------------------------------------
 # Assertions
 # ---------------------------------------------------------------------------
-puts "=== Verification ==="
-
 def final_state(events)
   events.select { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) }
         .last&.status&.state
@@ -143,8 +145,11 @@ a_ok = final_state(all_events["A"]) == "completed"
 b_ok = final_state(all_events["B"]) == "canceled"
 c_ok = final_state(all_events["C"]) == "completed"
 
-puts "  Task A completed normally : #{a_ok ? 'PASS' : 'FAIL'}"
-puts "  Task B was cancelled      : #{b_ok ? 'PASS' : 'FAIL'}"
-puts "  Task C completed normally : #{c_ok ? 'PASS' : 'FAIL'}"
-puts
+puts <<~HEREDOC
+  === Verification ===
+    Task A completed normally : #{a_ok ? 'PASS' : 'FAIL'}
+    Task B was cancelled      : #{b_ok ? 'PASS' : 'FAIL'}
+    Task C completed normally : #{c_ok ? 'PASS' : 'FAIL'}
+
+HEREDOC
 puts(a_ok && b_ok && c_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/05_cancellation/server.rb

@@ -69,9 +69,11 @@ card = A2A::Models::AgentCard.new(
   ]
 )
 
-puts "Starting SlowAgent on http://localhost:9292"
-puts "Each task takes #{SlowExecutor::STEPS * SlowExecutor::STEP_SEC}s to complete without cancellation."
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting SlowAgent on http://localhost:9292
+  Each task takes #{SlowExecutor::STEPS * SlowExecutor::STEP_SEC}s to complete without cancellation.
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(agent_card: card, executor: SlowExecutor.new).run

data/examples/06_push_notifications/client.rb

@@ -44,9 +44,11 @@ end
 webhook_thread = Thread.new { webhook_server.start }
 at_exit { webhook_server.shutdown }
 
-puts
-puts "=== Webhook receiver listening on #{WEBHOOK_URL} ==="
-puts
+puts <<~HEREDOC
+
+  === Webhook receiver listening on #{WEBHOOK_URL} ===
+
+HEREDOC
 
 # ---------------------------------------------------------------------------
 # Confirm the server is up and supports push notifications
@@ -54,12 +56,14 @@ puts
 base_client = A2A.client(url: A2A_URL)
 card        = base_client.agent_card
 
-puts "=== Agent Card ==="
-puts "  Name:               #{card.name}"
-puts "  Description:        #{card.description}"
-puts "  push_notifications: #{card.capabilities&.push_notifications}"
-puts "  streaming:          #{card.capabilities&.streaming}"
-puts
+puts <<~HEREDOC
+  === Agent Card ===
+    Name:               #{card.name}
+    Description:        #{card.description}
+    push_notifications: #{card.capabilities&.push_notifications}
+    streaming:          #{card.capabilities&.streaming}
+
+HEREDOC
 abort "Agent does not advertise push notification support." unless card.capabilities&.push_notifications
 divider
 
@@ -121,10 +125,12 @@ divider
 # The server posts after each step; we print each payload as it lands.
 # Stop when we see a final=true delivery.
 # ---------------------------------------------------------------------------
-puts
-puts "Watching webhook for incoming push notifications…"
-puts "(the client has NO open SSE connection — all updates arrive out-of-band)"
-puts
+puts <<~HEREDOC
+
+  Watching webhook for incoming push notifications…
+  (the client has NO open SSE connection — all updates arrive out-of-band)
+
+HEREDOC
 
 received = []
 loop do
@@ -164,29 +170,32 @@ sse_thread.join(5)
 # Summary
 # ---------------------------------------------------------------------------
 divider
-puts
-puts "=== Summary ==="
-puts "  Push notifications received : #{received.length}"
-puts "  States delivered            : #{received.map { |p| p.dig("status", "state") }.join(" → ")}"
-puts "  Final delivery seen         : #{received.any? { |p| p["final"] } ? 'yes' : 'no'}"
-puts "  Config cleaned up           : #{list_after.empty? ? 'yes' : 'no'}"
-puts
+puts <<~HEREDOC
+
+  === Summary ===
+    Push notifications received : #{received.length}
+    States delivered            : #{received.map { |p| p.dig("status", "state") }.join(" → ")}
+    Final delivery seen         : #{received.any? { |p| p["final"] } ? 'yes' : 'no'}
+    Config cleaned up           : #{list_after.empty? ? 'yes' : 'no'}
+
+HEREDOC
 
 # ---------------------------------------------------------------------------
 # Verification
 # ---------------------------------------------------------------------------
-puts "=== Verification ==="
 states     = received.map { |p| p.dig("status", "state") }
 last_state = states.last
-
 push_ok    = received.length >= 2
 final_ok   = received.last&.fetch("final", false)
 state_ok   = last_state == "completed"
 cleanup_ok = list_after.empty?
-
-puts "  Push notifications received (≥2) : #{push_ok    ? 'PASS' : 'FAIL'}"
-puts "  Final push delivery seen         : #{final_ok   ? 'PASS' : 'FAIL'}"
-puts "  Final state is completed         : #{state_ok   ? 'PASS' : 'FAIL'}"
-puts "  Config deleted successfully      : #{cleanup_ok ? 'PASS' : 'FAIL'}"
-puts
-puts(push_ok && final_ok && state_ok && cleanup_ok ? "All assertions passed." : "One or more assertions failed.")
+all_ok     = push_ok && final_ok && state_ok && cleanup_ok
+puts <<~HEREDOC
+  === Verification ===
+    Push notifications received (≥2) : #{push_ok    ? 'PASS' : 'FAIL'}
+    Final push delivery seen         : #{final_ok   ? 'PASS' : 'FAIL'}
+    Final state is completed         : #{state_ok   ? 'PASS' : 'FAIL'}
+    Config deleted successfully      : #{cleanup_ok ? 'PASS' : 'FAIL'}
+
+HEREDOC
+puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/06_push_notifications/server.rb

@@ -109,11 +109,13 @@ card = A2A::Models::AgentCard.new(
   ]
 )
 
-puts "Starting PushAgent on http://localhost:9292"
-puts "  push_notifications: true"
-puts "  #{PushExecutor::STEPS} steps × #{PushExecutor::STEP_SEC}s = ~#{(PushExecutor::STEPS * PushExecutor::STEP_SEC).to_i}s per task"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting PushAgent on http://localhost:9292
+    push_notifications: true
+    #{PushExecutor::STEPS} steps × #{PushExecutor::STEP_SEC}s = ~#{(PushExecutor::STEPS * PushExecutor::STEP_SEC).to_i}s per task
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(
   agent_card:        card,

data/examples/07_agent_chaining/client.rb

@@ -54,16 +54,19 @@ inputs = [
   "simple is better than complex"
 ]
 
-puts
-puts "=== Pipeline calls (client speaks only to /pipeline) ==="
-puts
+puts <<~HEREDOC
+
+  === Pipeline calls (client speaks only to /pipeline) ===
+
+HEREDOC
 
 results = inputs.map do |text|
   task   = pipeline.send_task(message: A2A::Models::Message.user(text))
   output = artifact_text(task)
-  puts "Input:  #{text}"
-  puts output.lines.map { |l| "  #{l}" }.join
-  puts
+  puts <<~HEREDOC
+    Input:  #{text}
+    #{output.lines.map { |l| "  #{l}" }.join}
+  HEREDOC
   { input: text, output: output, state: task.status.state }
 end
 
@@ -72,10 +75,11 @@ divider
 # ---------------------------------------------------------------------------
 # Call sub-agents directly to show they work standalone
 # ---------------------------------------------------------------------------
-puts
-puts "=== Sub-agents called directly (verification) ==="
-puts
+puts <<~HEREDOC
+
+  === Sub-agents called directly (verification) ===
 
+HEREDOC
 sample = "hello world from A2A"
 
 reverse_task = A2A.client(url: REVERSE_URL).send_task(
@@ -85,19 +89,18 @@ shout_task = A2A.client(url: SHOUT_URL).send_task(
   message: A2A::Models::Message.user(sample)
 )
 
-puts "  Input:                  #{sample}"
-puts "  /reverse result:        #{artifact_text(reverse_task)}"
-puts "  /shout   result:        #{artifact_text(shout_task)}"
-puts
+puts <<~HEREDOC
+  Input:                  #{sample}
+  /reverse result:        #{artifact_text(reverse_task)}
+  /shout   result:        #{artifact_text(shout_task)}
+
+HEREDOC
 
 divider
 
 # ---------------------------------------------------------------------------
 # Verification
 # ---------------------------------------------------------------------------
-puts
-puts "=== Verification ==="
-
 all_completed = results.all? { |r| r[:state] == "completed" }
 
 pipeline_correct = results.all? do |r|
@@ -109,12 +112,15 @@ end
 
 standalone_reverse_ok = artifact_text(reverse_task) == sample.split.reverse.join(" ")
 standalone_shout_ok   = artifact_text(shout_task)   == sample.upcase
+all_ok                = all_completed && pipeline_correct && standalone_reverse_ok && standalone_shout_ok
 
-puts "  All pipeline tasks completed       : #{all_completed          ? 'PASS' : 'FAIL'}"
-puts "  Pipeline output matches chain      : #{pipeline_correct       ? 'PASS' : 'FAIL'}"
-puts "  ReverseAgent standalone correct    : #{standalone_reverse_ok  ? 'PASS' : 'FAIL'}"
-puts "  ShoutAgent standalone correct      : #{standalone_shout_ok    ? 'PASS' : 'FAIL'}"
-puts
+puts <<~HEREDOC
+
+  === Verification ===
+    All pipeline tasks completed       : #{all_completed          ? 'PASS' : 'FAIL'}
+    Pipeline output matches chain      : #{pipeline_correct       ? 'PASS' : 'FAIL'}
+    ReverseAgent standalone correct    : #{standalone_reverse_ok  ? 'PASS' : 'FAIL'}
+    ShoutAgent standalone correct      : #{standalone_shout_ok    ? 'PASS' : 'FAIL'}
 
-all_ok = all_completed && pipeline_correct && standalone_reverse_ok && standalone_shout_ok
+HEREDOC
 puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/07_agent_chaining/server.rb

@@ -133,12 +133,14 @@ pipeline_card = make_card(
 # ---------------------------------------------------------------------------
 # Start the multi-agent server
 # ---------------------------------------------------------------------------
-puts "Starting multi-agent server on #{BASE_URL}"
-puts "  /reverse   → ReverseAgent"
-puts "  /shout     → ShoutAgent"
-puts "  /pipeline  → PipelineAgent (chains the other two)"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting multi-agent server on #{BASE_URL}
+    /reverse   → ReverseAgent
+    /shout     → ShoutAgent
+    /pipeline  → PipelineAgent (chains the other two)
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.multi_server(
   agents: {

data/examples/08_interrupted_states/client.rb

@@ -51,9 +51,11 @@ end
 # ---------------------------------------------------------------------------
 # Scenario A — input_required
 # ---------------------------------------------------------------------------
-puts
-puts "=== Scenario A: input_required (OrderAgent) ==="
-puts
+puts <<~HEREDOC
+
+  === Scenario A: input_required (OrderAgent) ===
+
+HEREDOC
 
 order = A2A.client(url: ORDER_URL)
 conv_a = SecureRandom.uuid
@@ -67,9 +69,11 @@ show_task("turn 1", task_a1)
 
 abort "Expected input_required, got #{task_a1.status.state}" unless task_a1.status.state == "input_required"
 
-puts
-puts "  Client reads the question and answers: 'pasta'"
-puts
+puts <<~HEREDOC
+
+  Client reads the question and answers: 'pasta'
+
+HEREDOC
 
 # Turn 2 — client answers with the same context_id
 task_a2 = order.send_task(message: msg("pasta", context_id: conv_a))
@@ -80,9 +84,11 @@ divider
 # ---------------------------------------------------------------------------
 # Scenario B — auth_required (with a wrong token first)
 # ---------------------------------------------------------------------------
-puts
-puts "=== Scenario B: auth_required (VaultAgent) ==="
-puts
+puts <<~HEREDOC
+
+  === Scenario B: auth_required (VaultAgent) ===
+
+HEREDOC
 
 vault  = A2A.client(url: VAULT_URL)
 conv_b = SecureRandom.uuid
@@ -96,9 +102,11 @@ show_task("turn 1", task_b1)
 
 abort "Expected auth_required, got #{task_b1.status.state}" unless task_b1.status.state == "auth_required"
 
-puts
-puts "  Client sends the wrong token: 'wrong-token'"
-puts
+puts <<~HEREDOC
+
+  Client sends the wrong token: 'wrong-token'
+
+HEREDOC
 
 # Turn 2 — wrong token; agent stays blocked
 task_b2 = vault.send_task(message: msg("wrong-token", context_id: conv_b))
@@ -106,9 +114,11 @@ show_task("turn 2", task_b2)
 
 abort "Expected auth_required, got #{task_b2.status.state}" unless task_b2.status.state == "auth_required"
 
-puts
-puts "  Client sends the correct token: 'open-sesame'"
-puts
+puts <<~HEREDOC
+
+  Client sends the correct token: 'open-sesame'
+
+HEREDOC
 
 # Turn 3 — correct token; agent unlocks
 task_b3 = vault.send_task(message: msg("open-sesame", context_id: conv_b))
@@ -119,9 +129,6 @@ divider
 # ---------------------------------------------------------------------------
 # Verification
 # ---------------------------------------------------------------------------
-puts
-puts "=== Verification ==="
-
 a_paused   = task_a1.status.state == "input_required"
 a_asked    = task_a1.status.message&.include?("Options:")
 a_complete = task_a2.status.state == "completed"
@@ -132,17 +139,21 @@ b_blocked2  = task_b2.status.state == "auth_required"
 b_complete  = task_b3.status.state == "completed"
 b_artifact  = task_b3.artifacts&.first&.parts&.first&.text&.include?("treasure")
 
-puts "  [order] turn 1 paused with input_required : #{a_paused   ? 'PASS' : 'FAIL'}"
-puts "  [order] turn 1 included a question        : #{a_asked    ? 'PASS' : 'FAIL'}"
-puts "  [order] turn 2 completed after answer     : #{a_complete ? 'PASS' : 'FAIL'}"
-puts "  [order] turn 2 artifact mentions pasta    : #{a_artifact ? 'PASS' : 'FAIL'}"
-puts
-puts "  [vault] turn 1 paused with auth_required  : #{b_blocked1 ? 'PASS' : 'FAIL'}"
-puts "  [vault] turn 2 stayed blocked (bad token) : #{b_blocked2 ? 'PASS' : 'FAIL'}"
-puts "  [vault] turn 3 completed after good token : #{b_complete ? 'PASS' : 'FAIL'}"
-puts "  [vault] turn 3 artifact contains secret   : #{b_artifact ? 'PASS' : 'FAIL'}"
-puts
-
 all_ok = a_paused && a_asked && a_complete && a_artifact &&
          b_blocked1 && b_blocked2 && b_complete && b_artifact
+
+puts <<~HEREDOC
+
+  === Verification ===
+    [order] turn 1 paused with input_required : #{a_paused   ? 'PASS' : 'FAIL'}
+    [order] turn 1 included a question        : #{a_asked    ? 'PASS' : 'FAIL'}
+    [order] turn 2 completed after answer     : #{a_complete ? 'PASS' : 'FAIL'}
+    [order] turn 2 artifact mentions pasta    : #{a_artifact ? 'PASS' : 'FAIL'}
+
+    [vault] turn 1 paused with auth_required  : #{b_blocked1 ? 'PASS' : 'FAIL'}
+    [vault] turn 2 stayed blocked (bad token) : #{b_blocked2 ? 'PASS' : 'FAIL'}
+    [vault] turn 3 completed after good token : #{b_complete ? 'PASS' : 'FAIL'}
+    [vault] turn 3 artifact contains secret   : #{b_artifact ? 'PASS' : 'FAIL'}
+
+HEREDOC
 puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/08_interrupted_states/server.rb

@@ -127,11 +127,13 @@ vault_card = make_card(
   path:        "/vault"
 )
 
-puts "Starting interrupted-states server on #{BASE_URL}"
-puts "  /order  → OrderAgent  (demonstrates input_required)"
-puts "  /vault  → VaultAgent  (demonstrates auth_required)"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting interrupted-states server on #{BASE_URL}
+    /order  → OrderAgent  (demonstrates input_required)
+    /vault  → VaultAgent  (demonstrates auth_required)
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.multi_server(
   agents: {

data/examples/09_multipart/client.rb

@@ -31,11 +31,13 @@ def header(title) = puts("\n  ── #{title} ──\n")
 client = A2A.client(url: URL)
 card   = client.agent_card
 
-puts
-puts "=== Agent Card ==="
-puts "  Name:        #{card.name}"
-puts "  Description: #{card.description}"
-puts
+puts <<~HEREDOC
+
+  === Agent Card ===
+    Name:        #{card.name}
+    Description: #{card.description}
+
+HEREDOC
 
 # ---------------------------------------------------------------------------
 # Send the task
@@ -73,9 +75,11 @@ artifact.parts.each_with_index do |part, i|
   elsif part.raw?
     header "binary  (media_type: #{part.media_type}, filename: #{part.filename})"
     bytes = part.decoded_bytes
-    puts "    base64 length : #{part.raw.length} chars"
-    puts "    decoded bytes : #{bytes.bytesize}"
-    puts "    content:"
+    puts <<~HEREDOC
+      base64 length : #{part.raw.length} chars
+      decoded bytes : #{bytes.bytesize}
+      content:
+    HEREDOC
     bytes.force_encoding("UTF-8").each_line { |l| puts "      #{l}" }
 
   elsif part.url?
@@ -96,15 +100,17 @@ json_part   = parts.find(&:json?)
 binary_part = parts.find(&:raw?)
 url_part    = parts.find(&:url?)
 
-puts
-puts "=== Verification ==="
-puts "  text   part present and non-empty : #{(text_part   && !text_part.text.empty?)           ? 'PASS' : 'FAIL'}"
-puts "  json   part present with hash     : #{(json_part   && json_part.data.is_a?(Hash))        ? 'PASS' : 'FAIL'}"
-puts "  binary part decodes correctly     : #{(binary_part && binary_part.decoded_bytes.bytesize > 0) ? 'PASS' : 'FAIL'}"
-puts "  url    part is a valid URL        : #{(url_part    && url_part.url.start_with?("https://")) ? 'PASS' : 'FAIL'}"
-puts "  json   part topic matches input   : #{(json_part   && json_part.data["topic"] == topic)  ? 'PASS' : 'FAIL'}"
-puts "  binary part is valid CSV          : #{(binary_part && binary_part.decoded_bytes.include?("rank")) ? 'PASS' : 'FAIL'}"
-puts
+puts <<~HEREDOC
+
+  === Verification ===
+    text   part present and non-empty : #{(text_part   && !text_part.text.empty?)           ? 'PASS' : 'FAIL'}
+    json   part present with hash     : #{(json_part   && json_part.data.is_a?(Hash))        ? 'PASS' : 'FAIL'}
+    binary part decodes correctly     : #{(binary_part && binary_part.decoded_bytes.bytesize > 0) ? 'PASS' : 'FAIL'}
+    url    part is a valid URL        : #{(url_part    && url_part.url.start_with?("https://")) ? 'PASS' : 'FAIL'}
+    json   part topic matches input   : #{(json_part   && json_part.data["topic"] == topic)  ? 'PASS' : 'FAIL'}
+    binary part is valid CSV          : #{(binary_part && binary_part.decoded_bytes.include?("rank")) ? 'PASS' : 'FAIL'}
+
+HEREDOC
 
 all_ok = text_part && json_part && binary_part && url_part &&
          !text_part.text.empty? &&

data/examples/09_multipart/server.rb

@@ -89,9 +89,11 @@ card = A2A::Models::AgentCard.new(
   ]
 )
 
-puts "Starting ReportAgent on http://localhost:9292"
-puts "Returns a 4-part artifact (text + JSON + binary + URL) for any topic."
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting ReportAgent on http://localhost:9292
+  Returns a 4-part artifact (text + JSON + binary + URL) for any topic.
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(agent_card: card, executor: ReportExecutor.new).run

data/examples/10_auth_headers/client.rb

@@ -31,19 +31,23 @@ auth_client   = A2A.client(url: URL, headers: { "Authorization" => "Bearer #{TOK
 # Agent card — public endpoint, both clients can discover it
 # ---------------------------------------------------------------------------
 puts
-puts "=== Agent Card (public — no auth required) ==="
 card = unauth_client.agent_card
-puts "  Name:        #{card.name}"
-puts "  Description: #{card.description}"
-puts
+puts <<~HEREDOC
+  === Agent Card (public — no auth required) ===
+    Name:        #{card.name}
+    Description: #{card.description}
+
+HEREDOC
 divider
 
 # ---------------------------------------------------------------------------
 # Unauthenticated client — rejected on RPC call
 # ---------------------------------------------------------------------------
-puts
-puts "=== Unauthenticated client — no Authorization header ==="
-puts
+puts <<~HEREDOC
+
+  === Unauthenticated client — no Authorization header ===
+
+HEREDOC
 
 unauth_error = nil
 begin
@@ -59,9 +63,11 @@ divider
 # ---------------------------------------------------------------------------
 # Authenticated client — accepted
 # ---------------------------------------------------------------------------
-puts
-puts "=== Authenticated client — Authorization: Bearer #{TOKEN} ==="
-puts
+puts <<~HEREDOC
+
+  === Authenticated client — Authorization: Bearer #{TOKEN} ===
+
+HEREDOC
 
 auth_task   = auth_client.send_task(message: A2A::Models::Message.user("hello from authorized client"))
 auth_result = auth_task.artifacts&.first&.parts&.first&.text
@@ -74,19 +80,19 @@ divider
 # ---------------------------------------------------------------------------
 # Verification
 # ---------------------------------------------------------------------------
-puts
-puts "=== Verification ==="
-
 card_ok      = card.name == "SecureAgent"
 rejected_ok  = unauth_error&.message&.include?("Unauthorized")
 accepted_ok  = auth_task.status.state == "completed"
 result_ok    = auth_result&.include?("[authorized]")
+all_ok       = card_ok && rejected_ok && accepted_ok && result_ok
 
-puts "  Agent card discoverable without auth : #{card_ok     ? 'PASS' : 'FAIL'}"
-puts "  Unauthenticated call rejected        : #{rejected_ok ? 'PASS' : 'FAIL'}"
-puts "  Authenticated call accepted          : #{accepted_ok ? 'PASS' : 'FAIL'}"
-puts "  Authenticated result is correct      : #{result_ok   ? 'PASS' : 'FAIL'}"
-puts
+puts <<~HEREDOC
+
+  === Verification ===
+    Agent card discoverable without auth : #{card_ok     ? 'PASS' : 'FAIL'}
+    Unauthenticated call rejected        : #{rejected_ok ? 'PASS' : 'FAIL'}
+    Authenticated call accepted          : #{accepted_ok ? 'PASS' : 'FAIL'}
+    Authenticated result is correct      : #{result_ok   ? 'PASS' : 'FAIL'}
 
-all_ok = card_ok && rejected_ok && accepted_ok && result_ok
+HEREDOC
 puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/10_auth_headers/server.rb

@@ -89,10 +89,12 @@ card = A2A::Models::AgentCard.new(
 inner_app = A2A.server(agent_card: card, executor: SecureEchoExecutor.new).rack_app
 auth_app  = BearerAuthMiddleware.new(inner_app, token: VALID_TOKEN)
 
-puts "Starting SecureAgent on http://localhost:9292"
-puts "  GET  /agentCard  — public (no auth required)"
-puts "  POST /           — requires Authorization: Bearer #{VALID_TOKEN}"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting SecureAgent on http://localhost:9292
+    GET  /agentCard  — public (no auth required)
+    POST /           — requires Authorization: Bearer #{VALID_TOKEN}
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A::Server::FalconRunner.new(auth_app, port: 9292).run

data/examples/11_sqlite_storage/client.rb

@@ -32,14 +32,14 @@ client = A2A.client(url: URL)
 # Phase: populate
 # ---------------------------------------------------------------------------
 if PHASE == "populate"
-  puts
-  puts "=== Phase 1: Populate — sending tasks to SQLite-backed server ==="
-  puts
-
   card = client.agent_card
-  puts "  Agent : #{card.name}"
-  puts "  DB    : shown in server output"
-  puts
+  puts <<~HEREDOC
+
+    === Phase 1: Populate — sending tasks to SQLite-backed server ===
+      Agent : #{card.name}
+      DB    : shown in server output
+
+  HEREDOC
 
   messages = [
     "alpha — first message",
@@ -51,28 +51,34 @@ if PHASE == "populate"
   messages.each do |text|
     task = client.send_task(message: A2A::Models::Message.user(text))
     ids << task.id
-    puts "  sent  : #{text.strip}"
-    puts "  id    : #{task.id}"
-    puts "  state : #{task.status.state}"
-    puts "  reply : #{task.artifacts.first&.parts&.first&.text}"
-    puts
+    puts <<~HEREDOC
+      sent  : #{text.strip}
+      id    : #{task.id}
+      state : #{task.status.state}
+      reply : #{task.artifacts.first&.parts&.first&.text}
+
+    HEREDOC
   end
 
   File.write(IDS_FILE, JSON.generate(ids))
   puts "  IDs written to #{IDS_FILE}"
   divider
   puts
-  puts "Populate complete. The server will now be stopped and restarted."
-  puts "The same database file will be passed to the new server instance."
-  puts
+  puts <<~HEREDOC
+    Populate complete. The server will now be stopped and restarted.
+    The same database file will be passed to the new server instance.
+
+  HEREDOC
 
 # ---------------------------------------------------------------------------
 # Phase: verify
 # ---------------------------------------------------------------------------
 else
-  puts
-  puts "=== Phase 2: Verify — confirming persistence after server restart ==="
-  puts
+  puts <<~HEREDOC
+
+    === Phase 2: Verify — confirming persistence after server restart ===
+
+  HEREDOC
 
   unless File.exist?(IDS_FILE)
     abort "IDs file not found: #{IDS_FILE} — run the populate phase first."
@@ -84,10 +90,12 @@ else
 
   results = ids.map do |id|
     task = client.get_task(id)
-    puts "  id    : #{id}"
-    puts "  state : #{task.status.state}"
-    puts "  reply : #{task.artifacts.first&.parts&.first&.text}"
-    puts
+    puts <<~HEREDOC
+      id    : #{id}
+      state : #{task.status.state}
+      reply : #{task.artifacts.first&.parts&.first&.text}
+
+    HEREDOC
     task
   rescue A2A::Error => e
     puts "  id    : #{id}  MISSING — #{e.message}"
@@ -100,15 +108,16 @@ else
   all_present   = results.none?(&:nil?)
   all_completed = results.compact.all? { |t| t.status.state == "completed" }
   count_ok      = results.length == ids.length
+  all_ok        = all_present && all_completed && count_ok
 
-  puts
-  puts "=== Verification ==="
-  puts "  All tasks present after restart : #{all_present   ? 'PASS' : 'FAIL'}"
-  puts "  All tasks in completed state    : #{all_completed ? 'PASS' : 'FAIL'}"
-  puts "  Task count matches (#{ids.length})         : #{count_ok     ? 'PASS' : 'FAIL'}"
-  puts
+  puts <<~HEREDOC
+
+    === Verification ===
+      All tasks present after restart : #{all_present   ? 'PASS' : 'FAIL'}
+      All tasks in completed state    : #{all_completed ? 'PASS' : 'FAIL'}
+      Task count matches (#{ids.length})         : #{count_ok     ? 'PASS' : 'FAIL'}
 
-  all_ok = all_present && all_completed && count_ok
+  HEREDOC
   puts(all_ok ? "All assertions passed." : "One or more assertions failed.")
   exit(all_ok ? 0 : 1)
 end

data/examples/11_sqlite_storage/server.rb

@@ -122,10 +122,12 @@ card = A2A::Models::AgentCard.new(
   ]
 )
 
-puts "Starting PersistentEchoAgent on http://localhost:9292"
-puts "  database: #{db_path}"
-puts "  existing tasks in DB: #{storage.size}"
-puts "Press Ctrl-C to stop."
-puts
+puts <<~HEREDOC
+  Starting PersistentEchoAgent on http://localhost:9292
+    database: #{db_path}
+    existing tasks in DB: #{storage.size}
+  Press Ctrl-C to stop.
+
+HEREDOC
 
 A2A.server(agent_card: card, executor: EchoExecutor.new, storage: storage).run

data/lib/simple_a2a/server/app.rb

@@ -106,18 +106,36 @@ module A2A
         msg_hash = params["message"]
         raise JsonRpc::InvalidParamsError, "message is required" unless msg_hash.is_a?(Hash)
         message  = Models::Message.from_hash(msg_hash)
+        task_id  = params["id"]
 
-        task = Models::Task.new(
-          status: Models::TaskStatus.new(state: Models::Types::TaskState::SUBMITTED)
-        )
-        self.class.storage.save(task)
+        task, ctx = if task_id
+          existing = self.class.storage.find!(task_id)
+          unless existing.status.interrupted?
+            raise UnsupportedOperationError,
+                  "Task #{task_id} cannot be resumed: state is #{existing.status.state}"
+          end
+          resume_ctx = Server::ResumeContext.new(
+            task:           existing,
+            message:        message,
+            resume_message: message,
+            storage:        self.class.storage,
+            event_router:   TaskBroadcast.new
+          )
+          [existing, resume_ctx]
+        else
+          new_task = Models::Task.new(
+            status: Models::TaskStatus.new(state: Models::Types::TaskState::SUBMITTED)
+          )
+          self.class.storage.save(new_task)
+          new_ctx = Server::Context.new(
+            task:         new_task,
+            message:      message,
+            storage:      self.class.storage,
+            event_router: TaskBroadcast.new
+          )
+          [new_task, new_ctx]
+        end
 
-        ctx = Server::Context.new(
-          task:         task,
-          message:      message,
-          storage:      self.class.storage,
-          event_router: TaskBroadcast.new
-        )
         self.class.executor.call(ctx)
         self.class.storage.save(task)
 

data/lib/simple_a2a/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module A2A
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_a2a
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -233,6 +233,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: flog
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Client and server for the A2A protocol — async-first, Rack-compatible,
   built on Falcon.
 email: