agent2agent 1.1.0 → 2.0.0

data/lib/a2a/server/sse/stream.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "protocol/http/body/writable"
+require "json"
+
+module A2A
+  class Server
+    module SSE
+      # Async-native SSE body built on ::Protocol::HTTP::Body::Writable.
+      #
+      # Falcon's protocol-rack passes ::Protocol::HTTP::Body::Readable subclasses
+      # through untouched — no Enumerable wrapping, no intermediate buffering.
+      # This gives us true async streaming with backpressure for free.
+      #
+      # The gospel (protocol-http) teaches:
+      #   - Writable is a producer/consumer queue body
+      #   - write() pushes chunks; read() pops them (blocks when empty)
+      #   - close_write signals EOF (reader gets nil)
+      #   - Client disconnect raises on next write()
+      #
+      # Usage:
+      #
+      #   stream = A2A::Server::SSE::RestStream.new(task_id: "t1", context_id: "c1")
+      #
+      #   Async do
+      #     stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "..." })
+      #     stream.status_update(status: { state: "TASK_STATE_COMPLETED", timestamp: "..." })
+      #     stream.finish
+      #   end
+      #
+      #   # Return as Rack body — Falcon streams it natively
+      #   [200, { "content-type" => "text/event-stream" }, stream]
+      #
+      class Stream < ::Protocol::HTTP::Body::Writable
+        SSE_HEADERS = {
+          "content-type"      => "text/event-stream",
+          "cache-control"     => "no-cache, no-transform",
+          "x-accel-buffering" => "no",
+          "connection"        => "keep-alive",
+        }.freeze
+
+        attr_reader :task_id, :context_id
+
+        def initialize(task_id:, context_id:, **options)
+          @task_id    = task_id
+          @context_id = context_id
+          super(**options)
+        end
+
+        # Emit an SSE event.
+        #
+        # @param data [Hash, String] the event payload (Hashes are JSON-encoded)
+        # @param type [String, nil] optional SSE event type field
+        # @param id   [String, nil] optional SSE event id field
+        #
+        def event(data, type: nil, id: nil)
+          payload = data.is_a?(String) ? data : JSON.generate(data)
+
+          buf = String.new
+          buf << "event: #{type}\n" if type
+          buf << "id: #{id}\n" if id
+
+          # SSE spec: each line of data gets its own `data:` prefix.
+          # For single-line JSON this is one line; multi-line is handled correctly.
+          payload.each_line do |line|
+            buf << "data: #{line.chomp}\n"
+          end
+          buf << "\n" # blank line terminates the event
+
+          write(buf)
+        end
+
+        # Signal end-of-stream.
+        # The reader will receive nil on next read(), closing the SSE connection.
+        def finish
+          close_write
+        end
+
+        # Convenience: the SSE headers to return in the Rack response.
+        # Returns a fresh copy — Rack response headers must be mutable,
+        # since middleware further up the stack (e.g. Rails' RequestId)
+        # adds headers in place.
+        def self.headers
+          SSE_HEADERS.dup
+        end
+
+        # --- Typed event emitters -------------------------------------------
+        #
+        # Dynamically generated from the StreamResponse schema.
+        # Each property in StreamResponse (task, message, statusUpdate,
+        # artifactUpdate) gets a snake_case method that:
+        #
+        #   1. Injects @task_id and @context_id (using the correct key name
+        #      for each type — Task uses `id`, others use `task_id`)
+        #   2. Builds the schema Definition from kwargs
+        #   3. Wraps it in the StreamResponse envelope
+        #   4. Calls #event to emit the SSE wire format
+        #
+        # This means you never pass task_id/context_id manually:
+        #
+        #   stream.task(status: { state: "TASK_STATE_WORKING" })
+        #   stream.artifact_update(artifact: { ... }, append: false, last_chunk: true)
+        #   stream.status_update(status: { state: "TASK_STATE_COMPLETED" })
+        #   stream.message(role: "ROLE_AGENT", parts: [{ text: "Hello" }])
+        #
+
+        stream_response = A2A::Protocol::JsonSchema["Stream Response"]
+
+        stream_response.property_refs.each do |camel_key, (_kind, title)|
+          target_props = A2A::Protocol::JsonSchema[title].schema_properties
+
+          # Task uses `id` for the task identifier; the other three use `taskId`
+          task_id_key = target_props.include?("id") ? :id : :task_id
+
+          # camelCase -> snake_case method name
+          method_name = camel_key
+            .gsub(/([A-Z])/) { "_#{$1.downcase}" }
+            .delete_prefix("_")
+
+          define_method(method_name) do |**kwargs|
+            merged = { task_id_key => @task_id, context_id: @context_id }.merge(kwargs)
+            event({ camel_key => A2A::Protocol::JsonSchema[title].new(merged).to_h })
+          end
+        end
+      end
+    end
+end
+end
+
+__END__
+  require "async"
+
+  describe "A2A::Server::SSE::Stream" do
+    it "formats SSE events correctly" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.event({ "task" => { "id" => "t1" } })
+      stream.finish
+
+      chunk = stream.read
+      chunk.should.include("data: ")
+      chunk.should.include('"task"')
+      chunk.should.end_with("\n\n")
+
+      # After finish, read returns nil
+      stream.read.should.be.nil
+    end
+
+    it "includes event type when provided" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.event("hello", type: "ping")
+      stream.finish
+
+      chunk = stream.read
+      chunk.should.include("event: ping\n")
+      chunk.should.include("data: hello\n")
+    end
+
+    it "includes event id when provided" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.event("test", id: "42")
+      stream.finish
+
+      chunk = stream.read
+      chunk.should.include("id: 42\n")
+    end
+
+    it "is a ::Protocol::HTTP::Body::Readable" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+      stream.is_a?(::Protocol::HTTP::Body::Readable).should == true
+    end
+
+    it "provides standard SSE headers" do
+      headers = A2A::Server::SSE::Stream.headers
+      headers["content-type"].should == "text/event-stream"
+      headers["cache-control"].should.include("no-cache")
+    end
+
+    it "stores task_id and context_id" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+      stream.task_id.should == "t1"
+      stream.context_id.should == "c1"
+    end
+
+    # --- Typed emit methods ---
+
+    it "#task emits a task event with injected id and context_id" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "2025-01-01T00:00:00Z" })
+      stream.finish
+
+      chunk = stream.read
+      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
+      parsed["task"]["id"].should == "t1"
+      parsed["task"]["contextId"].should == "c1"
+      parsed["task"]["status"]["state"].should == "TASK_STATE_WORKING"
+    end
+
+    it "#status_update emits with injected task_id and context_id" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      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["statusUpdate"]["taskId"].should == "t1"
+      parsed["statusUpdate"]["contextId"].should == "c1"
+      parsed["statusUpdate"]["status"]["state"].should == "TASK_STATE_COMPLETED"
+    end
+
+    it "#artifact_update emits with injected task_id and context_id" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.artifact_update(
+        artifact: { artifact_id: "a1", parts: [{ text: "hello" }] },
+        append: false,
+        last_chunk: true
+      )
+      stream.finish
+
+      chunk = stream.read
+      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
+      parsed["artifactUpdate"]["taskId"].should == "t1"
+      parsed["artifactUpdate"]["contextId"].should == "c1"
+      parsed["artifactUpdate"]["artifact"]["artifactId"].should == "a1"
+      parsed["artifactUpdate"]["append"].should == false
+      parsed["artifactUpdate"]["lastChunk"].should == true
+    end
+
+    it "#message emits with injected task_id and context_id" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.message(
+        message_id: "m1",
+        role: "ROLE_AGENT",
+        parts: [{ text: "Hello" }]
+      )
+      stream.finish
+
+      chunk = stream.read
+      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
+      parsed["message"]["taskId"].should == "t1"
+      parsed["message"]["contextId"].should == "c1"
+      parsed["message"]["role"].should == "ROLE_AGENT"
+    end
+
+    it "typed methods allow overriding injected values" do
+      stream = A2A::Server::SSE::Stream.new(task_id: "t1", context_id: "c1")
+
+      stream.task(id: "override", status: { state: "TASK_STATE_WORKING" })
+      stream.finish
+
+      chunk = stream.read
+      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
+      parsed["task"]["id"].should == "override"
+    end
+  end

data/lib/a2a/server/triage.rb

@@ -10,7 +10,7 @@ module A2A
     # Reads the raw protocol data left in env by the binding middleware
     # (JSON-RPC method name or HTTP verb + path), looks up the matching
     # Proto::Operation, wraps the request body into a Schema::Definition,
-    # and sets env keys for downstream consumption by the Dispatcher.
+    # and sets env keys for downstream consumption by the agent.
     #
     # Env keys read:
     #   "a2a.json_rpc_method" — set by Bindings::JsonRpc
@@ -58,14 +58,14 @@ module A2A
 
         def resolve_operation(env)
           if env["a2a.json_rpc_method"]
-            Proto.operation(env["a2a.json_rpc_method"])
+            Protocol::Protobuf.operation(env["a2a.json_rpc_method"])
           elsif env["a2a.verb"] && env["a2a.path"]
             match_rest_operation(env["a2a.verb"], env["a2a.path"])
           end
         end
 
         def match_rest_operation(verb, path)
-          Proto.operations.find do |op|
+          Protocol::Protobuf.operations.find do |op|
             op.http_bindings.any? do |b|
               b.verb == verb && path_matches?(b.path, path)
             end
@@ -80,7 +80,10 @@ module A2A
         end
 
         def pattern_to_regex(pattern)
-          re = pattern.gsub(/\{[^}]+\}/, '([^/]+)')
+          # Path params must not swallow ":" — custom-method suffixes like
+          # "/tasks/{id=*}:subscribe" would otherwise be captured into the
+          # id by plainer patterns like "/tasks/{id=*}".
+          re = pattern.gsub(/\{[^}]+\}/, '([^/:]+)')
           /\A#{re}\z/
         end
 
@@ -95,3 +98,31 @@ module A2A
     end
   end
 end
+
+__END__
+  describe "A2A::Server::Triage" do
+    triage = -> (env) { A2A::Server::Triage.new(->(e) { e }).call(env) }
+
+    it "resolves GET /tasks/{id} to GetTask" do
+      env = triage.({ "a2a.verb" => "get", "a2a.path" => "/tasks/abc-123", "a2a.body" => {} })
+      env["a2a.operation"].should == "GetTask"
+      env["a2a.request"].id.should == "abc-123"
+    end
+
+    it "resolves GET /tasks/{id}:subscribe to SubscribeToTask, not GetTask" do
+      env = triage.({ "a2a.verb" => "get", "a2a.path" => "/tasks/abc-123:subscribe", "a2a.body" => {} })
+      env["a2a.operation"].should == "SubscribeToTask"
+      env["a2a.request"].id.should == "abc-123"
+    end
+
+    it "resolves POST /tasks/{id}:cancel to CancelTask" do
+      env = triage.({ "a2a.verb" => "post", "a2a.path" => "/tasks/abc-123:cancel", "a2a.body" => {} })
+      env["a2a.operation"].should == "CancelTask"
+      env["a2a.request"].id.should == "abc-123"
+    end
+
+    it "returns UnsupportedOperationError for an unknown path" do
+      result = triage.({ "a2a.verb" => "get", "a2a.path" => "/nope", "a2a.body" => {} })
+      result.should.be.is_a(A2A::UnsupportedOperationError)
+    end
+  end

data/lib/a2a/server/well_known.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  class Server
+    # Rack middleware that serves the agent card at the well-known
+    # discovery path. All other requests pass through untouched.
+    #
+    class WellKnown
+      PATH = "/.well-known/agent-card.json"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless env["PATH_INFO"] == PATH
+
+        card = env["a2a.agent_card"] || {}
+        body = card.is_a?(Hash) ? card : card.to_h
+        [200, { "content-type" => "application/json" }, [JSON.generate(body)]]
+      end
+    end
+  end
+end

data/lib/a2a/server.rb

@@ -4,57 +4,49 @@ require "bundler/setup"
 require "a2a"
 
 require "a2a/server/env"
+require "a2a/server/well_known"
 require "a2a/server/triage"
-require "a2a/server/dispatcher"
 
 module A2A
   # Rack application that exposes an A2A-compliant agent server.
   #
-  # Composes two separate middleware stacks, one for each protocol binding:
+  # Composes a single linear middleware stack. Each middleware checks the
+  # request path and either handles the request or passes it downstream:
   #
-  #   /.well-known/agent-card.json
-  #     → Env → serve agent card
+  #   Env                 → injects shared context into the env
+  #   WellKnown           → serves /.well-known/agent-card.json
+  #   Bindings::Grpc      → /grpc (reserved) → 501 Not Implemented
+  #   Bindings::Rest      → /rest (HTTP+JSON/REST)
+  #   Bindings::JsonRpc   → everything else (JSON-RPC 2.0)
+  #   SSEStream           → offers env["a2a.stream"] to the agent
+  #   Triage              → resolves the target operation
+  #   ExtractMessage      → sets env["a2a.message"] when a message is present
+  #   LimitHistoryLength  → sets env["a2a.history_length"]
+  #   LimitPaginationSize → sets env["a2a.page_size"]
+  #   Agent               → the terminal app (your block)
   #
-  #   /a2a  (JSON-RPC 2.0)
-  #     → Env → Bindings::JsonRpc → Triage → Dispatcher
+  # The block is the terminal rack app — it is executed at the end of
+  # the stack, wrapped in the A2A::Agent error boundary. Usage
+  # (A2A.agent is a shorthand for this):
   #
-  #   /     (HTTP+JSON/REST)
-  #     → Env → Bindings::Rest → Triage → Dispatcher
-  #
-  # Usage:
-  #
-  #   agent = A2A::Agent.new do
-  #     on "SendMessage" do
-  #       respond_with -> (env) {
-  #         A2A::Schema["Send Message Response"].new({})
-  #       }
+  #   app = A2A::Server.new(agent_card: { "name" => "My Agent", ... }) do |env|
+  #     case env["a2a.operation"]
+  #     in "SendMessage"
+  #       A2A::Protocol::JsonSchema["Send Message Response"].new({})
   #     end
   #   end
   #
-  #   app = A2A::Server.new(agent_card: { "name" => "My Agent", ... })
-  #   app.register(agent)
-  #
   #   run app
   #
   class Server
-    def initialize(agent_card: {})
-      @agent_card = agent_card
-      @dispatcher = Dispatcher.new
-      @app        = build_app
-    end
+    def initialize(agent_card: {}, history_length: 100, page_size: 100, &block)
+      raise ArgumentError, "Server requires a block" unless block
 
-    # Register an Agent or a plain handler on the internal dispatcher.
-    #
-    # Accepts either:
-    #   - An Agent (responds to #handlers) — registers all its handlers
-    #   - A plain handler (responds to #operations and #call)
-    #
-    def register(handler)
-      if handler.respond_to?(:handlers)
-        handler.handlers.each { |h| @dispatcher.register(h) }
-      else
-        @dispatcher.register(handler)
-      end
+      @agent_card     = agent_card
+      @agent          = Agent.new(&block)
+      @history_length = history_length
+      @page_size      = page_size
+      @app            = build_app
     end
 
     def call(env)
@@ -64,34 +56,28 @@ module A2A
     private
 
       def build_app
+        require "a2a/server/bindings/grpc"
         require "a2a/server/bindings/json_rpc"
         require "a2a/server/bindings/rest"
+        require "a2a/server/middleware"
 
-        agent_card = @agent_card
-        dispatcher = @dispatcher
+        agent_card     = @agent_card
+        agent          = @agent
+        history_length = @history_length
+        page_size      = @page_size
 
         Rack::Builder.app do
           use A2A::Server::Env, agent_card: agent_card
-
-          map "/.well-known/agent-card.json" do
-            run ->(env) {
-              card = env["a2a.agent_card"] || {}
-              body = card.is_a?(Hash) ? card : card.to_h
-              [200, { "content-type" => "application/json" }, [JSON.generate(body)]]
-            }
-          end
-
-          map "/a2a" do
-            use A2A::Server::Bindings::JsonRpc
-            use A2A::Server::Triage
-            run dispatcher
-          end
-
-          map "/" do
-            use A2A::Server::Bindings::Rest
-            use A2A::Server::Triage
-            run dispatcher
-          end
+          use A2A::Server::WellKnown
+          use A2A::Server::Bindings::Grpc,    path_prefix: "/grpc"
+          use A2A::Server::Bindings::Rest,    path_prefix: "/rest"
+          use A2A::Server::Bindings::JsonRpc, path_prefix: "/"
+          use A2A::Server::Middleware::SSEStream
+          use A2A::Server::Triage
+          use A2A::Server::Middleware::ExtractMessage
+          use A2A::Server::Middleware::LimitHistoryLength, history_length
+          use A2A::Server::Middleware::LimitPaginationSize, page_size
+          run agent
         end
       end
   end

data/lib/a2a/test_helpers.rb

@@ -2,86 +2,45 @@
 
 require "a2a"
 require "a2a/agent"
-require "a2a/proto"
-require "a2a/schema"
+require "a2a/protocol/protobuf"
+require "a2a/protocol/json_schema"
 
 module A2A
   module TestHelpers
-    # Returns a stub agent that handles all A2A operations with
+    # Returns a stub agent server that handles all A2A operations with
     # minimal valid responses. Useful for integration tests that
     # need a working server without real business logic.
-    def self.stub_agent
-      Agent.new do
-        on "SendMessage" do
-          respond_with -> (env) {
-            A2A::Schema["Send Message Response"].new({})
-          }
-        end
-
-        on "SendStreamingMessage" do
-          respond_with -> (env) {
-            A2A::Schema["Stream Response"].new({})
-          }
-        end
-
-        on "GetTask" do
-          respond_with -> (env) {
-            A2A::Schema["Task"].new(
-              "id"        => "test-id",
-              "contextId" => "ctx-1",
-              "status"    => { "state" => "TASK_STATE_COMPLETED", "timestamp" => "2025-01-01T00:00:00Z" }
-            )
-          }
-        end
-
-        on "ListTasks" do
-          respond_with -> (env) {
-            A2A::Schema["List Tasks Response"].new({})
-          }
-        end
-
-        on "CancelTask" do
-          respond_with -> (env) {
-            A2A::Schema["Task"].new(
-              "id"        => "test-id",
-              "contextId" => "ctx-1",
-              "status"    => { "state" => "TASK_STATE_CANCELED", "timestamp" => "2025-01-01T00:00:00Z" }
-            )
-          }
-        end
-
-        on "SubscribeToTask" do
-          respond_with -> (env) {
-            A2A::Schema["Stream Response"].new({})
-          }
-        end
-
-        on "CreateTaskPushNotificationConfig" do
-          respond_with -> (env) {
-            A2A::Schema["Task Push Notification Config"].new("url" => "http://example.com")
-          }
-        end
-
-        on "GetTaskPushNotificationConfig" do
-          respond_with -> (env) {
-            A2A::Schema["Task Push Notification Config"].new("url" => "http://example.com")
-          }
-        end
-
-        on "ListTaskPushNotificationConfigs" do
-          respond_with -> (env) {
-            A2A::Schema["List Task Push Notification Configs Response"].new({})
-          }
-        end
-
-        on "GetExtendedAgentCard" do
-          respond_with -> (env) {
-            A2A::Schema["Agent Card"].new("name" => "Test", "version" => "1.0")
-          }
-        end
-
-        on "DeleteTaskPushNotificationConfig" do
-          respond_with -> (env) { nil }
+    def self.stub_agent(agent_card: {})
+      schema = A2A::Protocol::JsonSchema
+
+      A2A.agent(agent_card: agent_card) do |env|
+        case env["a2a.operation"]
+        in "SendMessage"
+          schema["Send Message Response"].new({})
+        in "SendStreamingMessage" | "SubscribeToTask"
+          schema["Stream Response"].new({})
+        in "GetTask"
+          schema["Task"].new(
+            "id"        => "test-id",
+            "contextId" => "ctx-1",
+            "status"    => { "state" => "TASK_STATE_COMPLETED", "timestamp" => "2025-01-01T00:00:00Z" }
+          )
+        in "CancelTask"
+          schema["Task"].new(
+            "id"        => "test-id",
+            "contextId" => "ctx-1",
+            "status"    => { "state" => "TASK_STATE_CANCELED", "timestamp" => "2025-01-01T00:00:00Z" }
+          )
+        in "ListTasks"
+          schema["List Tasks Response"].new({})
+        in "CreateTaskPushNotificationConfig" | "GetTaskPushNotificationConfig"
+          schema["Task Push Notification Config"].new("url" => "http://example.com")
+        in "ListTaskPushNotificationConfigs"
+          schema["List Task Push Notification Configs Response"].new({})
+        in "GetExtendedAgentCard"
+          schema["Agent Card"].new("name" => "Test", "version" => "1.0")
+        in "DeleteTaskPushNotificationConfig"
+          nil
         end
       end
     end

data/lib/a2a/version.rb

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

data/lib/a2a.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "bundler/setup"
-require "scampi"
 require "json"
 require "json_schemer"
 require "async"
@@ -13,18 +12,15 @@ module A2A
 end
 
 require "a2a/errors"
-require "a2a/proto"
-require "a2a/schema"
-require "a2a/schema/definition"
-require "a2a/schema/validation_error"
-require "a2a/sse"
+require "a2a/protocol"
+require "a2a/server/sse"
 require "a2a/agent"
 
 require "a2a/server"
 
-require "a2a/faraday/middleware/schema_request"
-require "a2a/faraday/middleware/json_rpc/request"
-require "a2a/faraday/middleware/json_rpc/response"
-require "a2a/faraday/middleware/rest/request"
-require "a2a/faraday/middleware/rest/response"
+require "a2a/client/middleware/schema_request"
+require "a2a/client/middleware/json_rpc/request"
+require "a2a/client/middleware/json_rpc/response"
+require "a2a/client/middleware/rest/request"
+require "a2a/client/middleware/rest/response"
 require "a2a/client"