agent2agent 1.0.7 → 1.1.0

data/lib/a2a/server/dispatcher.rb

@@ -6,115 +6,115 @@ require "a2a"
 
 module A2A
   class Server
-    # Routes incoming A2A operations to registered handler objects.
+    # Routes incoming A2A operations to their registered handler stacks.
     #
-    # Each handler declares the operations it handles via `#operations`.
-    # When an operation arrives, the dispatcher finds all matching handlers
-    # and calls them. Errors in one handler do not prevent others from running.
+    # Each operation maps to exactly one Rack app (a compiled middleware
+    # stack built by the Agent DSL). The Dispatcher is a terminal Rack app
+    # that reads env["a2a.operation"] set by Triage, looks up the matching
+    # route, and calls it.
     #
-    # The Dispatcher is a Rack app (terminal, not middleware). It reads
-    # env["a2a.operation"] set by Triage and fans out to matching handlers.
+    # Returns domain objects (A2A::Schema::Definition or A2A::Error) —
+    # the binding layer is responsible for formatting these into HTTP.
     #
     class Dispatcher
       def initialize
-        @handlers = Hash.new { |h, k| h[k] = [] }
+        @routes = {}
       end
 
       # Register a handler object.
       #
       # The handler must respond to:
       #   #operations -> Array(String)  (e.g. ["SendMessage", "GetTask"])
-      #   #call(env)  -> void           (sets env["a2a.result"])
+      #   #call(env)  -> A2A::Schema::Definition | A2A::Error
       #
       def register(handler)
         handler.operations.each do |op|
-          @handlers[op] << handler
+          @routes[op] = handler
           Console.info(self) { "Registered #{handler.class.name} for #{op}" }
         end
       end
 
       def call(env)
         operation = env["a2a.operation"]
+        app = @routes[operation]
 
-        if operation
-          dispatch(operation, env)
+        unless app
+          raise A2A::UnsupportedOperationError.new(
+            message: "Operation not supported: #{operation}"
+          )
         end
 
-        [200, {}, []]
+        app.call(env)
+      rescue A2A::Error => e
+        e
+      rescue => e
+        Console.error(self, "Handler raised #{e.class}: #{e.message}", e)
+        A2A::Error.new("Internal error", code: -32603, http_status: 500)
       end
 
       def handler_count
-        @handlers.values.flatten.size
+        @routes.size
       end
-
-      private
-
-        def dispatch(operation, env)
-          handlers = @handlers[operation]
-
-          if handlers.empty?
-            Console.debug(self) { "No handler for operation: #{operation}" }
-          else
-            handlers.each do |handler|
-              begin
-                handler.call(env)
-              rescue => e
-                Console.error(self, "Handler #{handler.class.name} raised #{e.class}", e)
-              end
-            end
-          end
-        end
     end
   end
 end
 
 test do
   describe "A2A::Server::Dispatcher" do
-    it "registers and dispatches to handlers" do
-      received = []
+    it "registers and dispatches to a handler" do
       handler = Object.new
       handler.define_singleton_method(:operations) { ["SendMessage"] }
-      handler.define_singleton_method(:call) { |env| received << env }
+      handler.define_singleton_method(:call) { |env| :dispatched }
 
       dispatcher = A2A::Server::Dispatcher.new
       dispatcher.register(handler)
       dispatcher.handler_count.should == 1
 
       env = { "a2a.operation" => "SendMessage" }
-      dispatcher.call(env)
-      received.length.should == 1
+      result = dispatcher.call(env)
+      result.should == :dispatched
     end
 
-    it "ignores operations with no matching handler" do
+    it "returns UnsupportedOperationError for unknown operations" do
       dispatcher = A2A::Server::Dispatcher.new
       env = { "a2a.operation" => "UnknownOp" }
-      lambda { dispatcher.call(env) }.should.not.raise
+      result = dispatcher.call(env)
+      result.should.be.is_a(A2A::UnsupportedOperationError)
+      result.code.should == -32004
     end
 
-    it "continues dispatching when a handler raises" do
-      results = []
-      bad_handler = Object.new
-      bad_handler.define_singleton_method(:operations) { ["SendMessage"] }
-      bad_handler.define_singleton_method(:call) { |_| raise "boom" }
+    it "returns A2A::Error when handler raises one" do
+      handler = Object.new
+      handler.define_singleton_method(:operations) { ["SendMessage"] }
+      handler.define_singleton_method(:call) { |_| raise A2A::TaskNotFoundError.new("t-1") }
+
+      dispatcher = A2A::Server::Dispatcher.new
+      dispatcher.register(handler)
+
+      result = dispatcher.call({ "a2a.operation" => "SendMessage" })
+      result.should.be.is_a(A2A::TaskNotFoundError)
+      result.code.should == -32001
+    end
 
-      good_handler = Object.new
-      good_handler.define_singleton_method(:operations) { ["SendMessage"] }
-      good_handler.define_singleton_method(:call) { |e| results << e }
+    it "returns internal error when handler raises unexpected exception" do
+      handler = Object.new
+      handler.define_singleton_method(:operations) { ["SendMessage"] }
+      handler.define_singleton_method(:call) { |_| raise "boom" }
 
       dispatcher = A2A::Server::Dispatcher.new
-      dispatcher.register(bad_handler)
-      dispatcher.register(good_handler)
+      dispatcher.register(handler)
 
-      env = { "a2a.operation" => "SendMessage" }
-      dispatcher.call(env)
-      results.length.should == 1
+      result = dispatcher.call({ "a2a.operation" => "SendMessage" })
+      result.should.be.is_a(A2A::Error)
+      result.code.should == -32603
+      result.http_status.should == 500
     end
 
     it "dispatches to multiple operations from one handler" do
       received = []
       handler = Object.new
       handler.define_singleton_method(:operations) { ["SendMessage", "GetTask"] }
-      handler.define_singleton_method(:call) { |env| received << env["a2a.operation"] }
+      handler.define_singleton_method(:call) { |env| received << env["a2a.operation"]; :ok }
 
       dispatcher = A2A::Server::Dispatcher.new
       dispatcher.register(handler)

data/lib/a2a/server/env.rb

@@ -7,19 +7,17 @@ module A2A
   class Server
     # Rack middleware that injects shared A2A context into the env.
     #
-    # Sets env["a2a.store"] and env["a2a.agent_card"] so downstream
-    # middleware and handlers can access them without coupling to
-    # any particular configuration mechanism.
+    # Sets env["a2a.agent_card"] so downstream middleware and handlers
+    # can access it without coupling to any particular configuration
+    # mechanism.
     #
     class Env
-      def initialize(app, agent_card: {}, store: TaskStore.new)
+      def initialize(app, agent_card: {})
         @app = app
         @agent_card = agent_card
-        @store = store
       end
 
       def call(env)
-        env["a2a.store"] = @store
         env["a2a.agent_card"] = @agent_card
         @app.call(env)
       end

data/lib/a2a/server/triage.rb

@@ -29,10 +29,11 @@ module A2A
       end
 
       def call(env)
+        Console.info(self) { "Triaging: #{env}" }
         op = resolve_operation(env)
 
         unless op
-          return [404, { "content-type" => "text/plain" }, ["Unknown operation"]]
+          return A2A::UnsupportedOperationError.new(message: "Unknown operation")
         end
 
         env["a2a.operation"]       = op.name

data/lib/a2a/server.rb

@@ -24,8 +24,10 @@ module A2A
   # Usage:
   #
   #   agent = A2A::Agent.new do
-  #     on "SendMessage" do |request|
-  #       respond A2A::Schema["Send Message Response"].new({})
+  #     on "SendMessage" do
+  #       respond_with -> (env) {
+  #         A2A::Schema["Send Message Response"].new({})
+  #       }
   #     end
   #   end
   #
@@ -35,9 +37,8 @@ module A2A
   #   run app
   #
   class Server
-    def initialize(agent_card: {}, store: TaskStore.new)
+    def initialize(agent_card: {})
       @agent_card = agent_card
-      @store      = store
       @dispatcher = Dispatcher.new
       @app        = build_app
     end
@@ -63,15 +64,14 @@ module A2A
     private
 
       def build_app
-        require "a2a/bindings/json_rpc"
-        require "a2a/bindings/rest"
+        require "a2a/server/bindings/json_rpc"
+        require "a2a/server/bindings/rest"
 
         agent_card = @agent_card
-        store      = @store
         dispatcher = @dispatcher
 
         Rack::Builder.app do
-          use A2A::Server::Env, agent_card: agent_card, store: store
+          use A2A::Server::Env, agent_card: agent_card
 
           map "/.well-known/agent-card.json" do
             run ->(env) {
@@ -82,13 +82,13 @@ module A2A
           end
 
           map "/a2a" do
-            use A2A::Bindings::JsonRpc
+            use A2A::Server::Bindings::JsonRpc
             use A2A::Server::Triage
             run dispatcher
           end
 
           map "/" do
-            use A2A::Bindings::Rest
+            use A2A::Server::Bindings::Rest
             use A2A::Server::Triage
             run dispatcher
           end

data/lib/a2a/sse/event_parser.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+
+module A2A
+  module SSE
+    # Parses raw SSE text chunks into typed StreamResponse schema objects.
+    #
+    # Faraday's `on_data` callback delivers raw text in arbitrary-sized
+    # chunks. This parser buffers them, extracts complete SSE events
+    # (delimited by blank lines), parses the JSON from `data:` lines,
+    # and yields A2A::Schema["Stream Response"] instances.
+    #
+    # For the JSON-RPC binding, the parser unwraps the JSON-RPC 2.0
+    # envelope (`{"jsonrpc":"2.0","id":N,"result":{...}}`) to extract
+    # the StreamResponse payload from `result`.
+    #
+    # Usage:
+    #
+    #   parser = A2A::SSE::EventParser.new(binding: :rest)
+    #
+    #   parser.feed("data: {\"task\":{\"id\":\"t1\"}}\n\n") do |event|
+    #     event.task.id  #=> "t1"
+    #   end
+    #
+    class EventParser
+      def initialize(binding:)
+        @binding = binding
+        @buffer  = String.new
+      end
+
+      # Feed a raw chunk of SSE text. Yields a StreamResponse for each
+      # complete event found in the buffer.
+      #
+      # @param chunk [String] raw SSE text from the wire
+      # @yieldparam event [A2A::Schema::Definition] a Stream Response instance
+      #
+      def feed(chunk)
+        @buffer << chunk
+
+        # SSE events are terminated by a blank line (\n\n).
+        # We split on that boundary, keeping any incomplete trailing data
+        # in the buffer for the next call.
+        while (idx = @buffer.index("\n\n"))
+          raw_event = @buffer.slice!(0, idx + 2)
+          payload = parse_event(raw_event)
+          yield A2A::Schema["Stream Response"].new(payload) if payload
+        end
+      end
+
+      private
+
+        # Extract JSON from `data:` lines and optionally unwrap JSON-RPC.
+        def parse_event(raw)
+          data_lines = raw.each_line
+            .select { |line| line.start_with?("data:") }
+            .map { |line| line.sub(/\Adata:\s?/, "").chomp }
+
+          return nil if data_lines.empty?
+
+          parsed = JSON.parse(data_lines.join("\n"))
+
+          case @binding
+          when :json_rpc then parsed["result"]
+          else parsed
+          end
+        rescue JSON::ParserError
+          nil
+        end
+    end
+  end
+end
+
+test do
+  describe "A2A::SSE::EventParser" do
+    # --- REST binding ---
+
+    it "parses a single complete SSE event" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      parser.feed("data: {\"task\":{\"id\":\"t1\",\"contextId\":\"c1\"}}\n\n") do |event|
+        events << event
+      end
+
+      events.size.should == 1
+      events[0].should.be.kind_of(A2A::Schema::Definition)
+      events[0].task.should.not.be.nil
+      events[0].task.id.should == "t1"
+    end
+
+    it "parses multiple events in a single chunk" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      chunk = [
+        "data: {\"task\":{\"id\":\"t1\",\"contextId\":\"c1\"}}\n\n",
+        "data: {\"statusUpdate\":{\"taskId\":\"t1\",\"contextId\":\"c1\",\"status\":{\"state\":\"TASK_STATE_COMPLETED\"}}}\n\n",
+      ].join
+
+      parser.feed(chunk) { |e| events << e }
+
+      events.size.should == 2
+      events[0].task.should.not.be.nil
+      events[1].status_update.should.not.be.nil
+    end
+
+    it "handles partial chunks via buffering" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      # First chunk: incomplete event
+      parser.feed("data: {\"task\":{\"id\"") { |e| events << e }
+      events.size.should == 0
+
+      # Second chunk: completes the event
+      parser.feed(":\"t1\",\"contextId\":\"c1\"}}\n\n") { |e| events << e }
+      events.size.should == 1
+      events[0].task.id.should == "t1"
+    end
+
+    it "handles events with event: and id: fields" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      chunk = "event: message\nid: 42\ndata: {\"task\":{\"id\":\"t1\",\"contextId\":\"c1\"}}\n\n"
+      parser.feed(chunk) { |e| events << e }
+
+      events.size.should == 1
+      events[0].task.id.should == "t1"
+    end
+
+    it "skips events with no data lines" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      parser.feed(": comment\n\n") { |e| events << e }
+      events.size.should == 0
+    end
+
+    it "skips events with invalid JSON" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      parser.feed("data: not-json\n\n") { |e| events << e }
+      events.size.should == 0
+    end
+
+    # --- JSON-RPC binding ---
+
+    it "unwraps JSON-RPC 2.0 envelope" do
+      parser = A2A::SSE::EventParser.new(binding: :json_rpc)
+      events = []
+
+      envelope = {
+        "jsonrpc" => "2.0",
+        "id"      => 1,
+        "result"  => {
+          "task" => { "id" => "t1", "contextId" => "c1" },
+        },
+      }
+
+      parser.feed("data: #{JSON.generate(envelope)}\n\n") { |e| events << e }
+
+      events.size.should == 1
+      events[0].task.should.not.be.nil
+      events[0].task.id.should == "t1"
+    end
+
+    it "handles multiple JSON-RPC events" do
+      parser = A2A::SSE::EventParser.new(binding: :json_rpc)
+      events = []
+
+      [
+        { "jsonrpc" => "2.0", "id" => 1, "result" => { "task" => { "id" => "t1", "contextId" => "c1" } } },
+        { "jsonrpc" => "2.0", "id" => 1, "result" => { "statusUpdate" => { "taskId" => "t1", "contextId" => "c1", "status" => { "state" => "TASK_STATE_COMPLETED" } } } },
+      ].each do |envelope|
+        parser.feed("data: #{JSON.generate(envelope)}\n\n") { |e| events << e }
+      end
+
+      events.size.should == 2
+      events[0].task.should.not.be.nil
+      events[1].status_update.should.not.be.nil
+    end
+
+    # --- Multi-line data ---
+
+    it "handles multi-line data fields" do
+      parser = A2A::SSE::EventParser.new(binding: :rest)
+      events = []
+
+      # JSON split across multiple data: lines
+      chunk = "data: {\"task\":\n" \
+              "data: {\"id\":\"t1\",\"contextId\":\"c1\"}}\n\n"
+
+      parser.feed(chunk) { |e| events << e }
+
+      events.size.should == 1
+      events[0].task.id.should == "t1"
+    end
+  end
+end

data/lib/a2a/sse/json_rpc_stream.rb

@@ -11,10 +11,12 @@ module A2A
     #
     # Usage:
     #
-    #   stream = A2A::SSE::JsonRpcStream.new(json_rpc_id: 1)
+    #   stream = A2A::SSE::JsonRpcStream.new(
+    #     task_id: "t1", context_id: "c1", json_rpc_id: 1
+    #   )
     #
     #   Async do
-    #     stream.event({ "task" => { ... } })
+    #     stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "..." })
     #     stream.finish
     #   end
     #
@@ -45,9 +47,11 @@ end
 test do
   describe "A2A::SSE::JsonRpcStream" do
     it "wraps events in JSON-RPC 2.0 envelopes" do
-      stream = A2A::SSE::JsonRpcStream.new(json_rpc_id: 42)
+      stream = A2A::SSE::JsonRpcStream.new(
+        task_id: "t1", context_id: "c1", json_rpc_id: 42
+      )
 
-      stream.event({ "task" => { "id" => "t1" } })
+      stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "2025-01-01T00:00:00Z" })
       stream.finish
 
       chunk = stream.read
@@ -58,9 +62,27 @@ test do
     end
 
     it "is a subclass of SSE::Stream" do
-      stream = A2A::SSE::JsonRpcStream.new(json_rpc_id: 1)
+      stream = A2A::SSE::JsonRpcStream.new(
+        task_id: "t1", context_id: "c1", json_rpc_id: 1
+      )
       stream.is_a?(A2A::SSE::Stream).should == true
       stream.is_a?(Protocol::HTTP::Body::Readable).should == true
     end
+
+    it "typed methods chain through JSON-RPC envelope" do
+      stream = A2A::SSE::JsonRpcStream.new(
+        task_id: "t1", context_id: "c1", json_rpc_id: 7
+      )
+
+      stream.status_update(status: { state: "TASK_STATE_COMPLETED", timestamp: "2025-01-01T00:00:00Z" })
+      stream.finish
+
+      chunk = stream.read
+      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
+      parsed["jsonrpc"].should == "2.0"
+      parsed["id"].should == 7
+      parsed["result"]["statusUpdate"]["taskId"].should == "t1"
+      parsed["result"]["statusUpdate"]["contextId"].should == "c1"
+    end
   end
 end

data/lib/a2a/sse/rest_stream.rb

@@ -15,10 +15,10 @@ module A2A
     #
     # Usage:
     #
-    #   stream = A2A::SSE::RestStream.new
+    #   stream = A2A::SSE::RestStream.new(task_id: "t1", context_id: "c1")
     #
     #   Async do
-    #     stream.event({ "task" => { ... } })
+    #     stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "..." })
     #     stream.finish
     #   end
     #
@@ -32,9 +32,9 @@ end
 test do
   describe "A2A::SSE::RestStream" do
     it "emits bare JSON events (no envelope)" do
-      stream = A2A::SSE::RestStream.new
+      stream = A2A::SSE::RestStream.new(task_id: "t1", context_id: "c1")
 
-      stream.event({ "statusUpdate" => { "taskId" => "t1" } })
+      stream.status_update(status: { state: "TASK_STATE_COMPLETED", timestamp: "2025-01-01T00:00:00Z" })
       stream.finish
 
       chunk = stream.read
@@ -43,8 +43,20 @@ test do
     end
 
     it "is a subclass of SSE::Stream" do
-      stream = A2A::SSE::RestStream.new
+      stream = A2A::SSE::RestStream.new(task_id: "t1", context_id: "c1")
       stream.is_a?(A2A::SSE::Stream).should == true
     end
+
+    it "injects task_id and context_id into typed events" do
+      stream = A2A::SSE::RestStream.new(task_id: "t1", context_id: "c1")
+
+      stream.task(status: { state: "TASK_STATE_WORKING" })
+      stream.finish
+
+      chunk = stream.read
+      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
+      parsed["task"]["id"].should == "t1"
+      parsed["task"]["contextId"].should == "c1"
+    end
   end
 end