agent2agent 1.1.0 → 2.0.0

data/lib/a2a/server/middleware/extract_message.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  class Server
+    module Middleware
+      # Extracts text from the request message's parts and sets
+      # `env["a2a.message"]` to the joined text string.
+      #
+      # Part of the A2A::Server middleware stack. Requests whose
+      # operation carries no message pass through untouched, so
+      # env["a2a.message"] is only present when a message is.
+      #
+      # Replaces the common `extract_text` lambda pattern found in examples:
+      #
+      #   extract_text = ->(message) {
+      #     parts = message.parts || []
+      #     parts.filter_map { |p| p.text }.join("\n")
+      #   }
+      #
+      class ExtractMessage
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          request = env["a2a.request"]
+
+          if request.respond_to?(:message) && (message = request.message)
+            parts = message.parts || []
+
+            env["a2a.message"] = parts.filter_map { |p|
+              p.respond_to?(:text) ? p.text : p["text"]
+            }.join("\n")
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+end
+end
+
+__END__
+  describe "A2A::Server::Middleware::ExtractMessage" do
+    it "extracts text from message parts" do
+      part1 = Object.new
+      part1.define_singleton_method(:text) { "hello" }
+      part2 = Object.new
+      part2.define_singleton_method(:text) { "world" }
+
+      message = Object.new
+      message.define_singleton_method(:parts) { [part1, part2] }
+
+      request = Object.new
+      request.define_singleton_method(:message) { message }
+
+      downstream = -> (env) { env["a2a.message"] }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+      env = { "a2a.request" => request }
+
+      result = mw.call(env)
+      result.should == "hello\nworld"
+    end
+
+    it "handles nil parts" do
+      message = Object.new
+      message.define_singleton_method(:parts) { nil }
+
+      request = Object.new
+      request.define_singleton_method(:message) { message }
+
+      downstream = -> (env) { env["a2a.message"] }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+      env = { "a2a.request" => request }
+
+      result = mw.call(env)
+      result.should == ""
+    end
+
+    it "skips parts without text" do
+      part1 = Object.new
+      part1.define_singleton_method(:text) { "hello" }
+      part2 = Object.new
+      part2.define_singleton_method(:text) { nil }
+
+      message = Object.new
+      message.define_singleton_method(:parts) { [part1, part2] }
+
+      request = Object.new
+      request.define_singleton_method(:message) { message }
+
+      downstream = -> (env) { env["a2a.message"] }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+      env = { "a2a.request" => request }
+
+      result = mw.call(env)
+      result.should == "hello"
+    end
+
+    it "handles hash-style parts" do
+      message = Object.new
+      message.define_singleton_method(:parts) { [{ "text" => "from hash" }] }
+
+      request = Object.new
+      request.define_singleton_method(:message) { message }
+
+      downstream = -> (env) { env["a2a.message"] }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+      env = { "a2a.request" => request }
+
+      result = mw.call(env)
+      result.should == "from hash"
+    end
+
+    it "passes through when the request has no message reader" do
+      request = Object.new
+
+      downstream = -> (env) { env.key?("a2a.message") }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+      env = { "a2a.request" => request }
+
+      mw.call(env).should == false
+    end
+
+    it "passes through when the message is nil" do
+      request = Object.new
+      request.define_singleton_method(:message) { nil }
+
+      downstream = -> (env) { env.key?("a2a.message") }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+      env = { "a2a.request" => request }
+
+      mw.call(env).should == false
+    end
+
+    it "passes through when there is no request" do
+      downstream = -> (env) { env.key?("a2a.message") }
+      mw = A2A::Server::Middleware::ExtractMessage.new(downstream)
+
+      mw.call({}).should == false
+    end
+  end

data/lib/a2a/{middleware → server/middleware}/fetch_task.rb

@@ -4,90 +4,84 @@ require "bundler/setup"
 require "a2a"
 
 module A2A
-  module Middleware
-    # Loads a task from the store and places it on `env["a2a.task"]`.
-    # Sets `env["a2a.task"]` to nil when the ID is absent or the task
-    # does not exist. Does not raise.
-    #
-    # The task ID is read from the request — by default from `request.id`.
-    # Use `id_field:` to read from a different field, and `from:` to
-    # read from a nested object on the request.
-    #
-    # Usage:
-    #
-    #   on "SendMessage" do
-    #     use A2A::Middleware::FetchTask, store: sqlite_store, id_field: :task_id, from: :message
-    #     respond_with -> (env) {
-    #       existing = env["a2a.task"]  # nil if new task
-    #     }
-    #   end
-    #
-    class FetchTask
-      def initialize(app, store:, id_field: :id, from: nil)
-        @app      = app
-        @store    = store
-        @id_field = id_field
-        @from     = from
+  class Server
+    module Middleware
+      # Loads a task from the store and places it on `env["a2a.task"]`.
+      # Sets `env["a2a.task"]` to nil when the ID is absent or the task
+      # does not exist. Does not raise.
+      #
+      # The task ID is read from the request — by default from `request.id`.
+      # Use `id_field:` to read from a different field, and `from:` to
+      # read from a nested object on the request.
+      #
+      # Not part of the default A2A::Server stack (it needs a store, and
+      # the ID field varies per operation) — wrap your agent with it:
+      #
+      #   agent = A2A::Server::Middleware::FetchTask.new(
+      #     A2A.agent { |env| existing = env["a2a.task"] }, # nil if new task
+      #     store: sqlite_store, id_field: :task_id, from: :message
+      #   )
+      #
+      class FetchTask
+        def initialize(app, store:, id_field: :id, from: nil)
+          @app      = app
+          @store    = store
+          @id_field = id_field
+          @from     = from
+        end
+
+        def call(env)
+          request = env["a2a.request"]
+          source  = @from ? request.public_send(@from) : request
+          id      = source.public_send(@id_field)
+
+          env["a2a.task"] = id.to_s.empty? ? nil : @store.get(id)
+
+          @app.call(env)
+        end
       end
 
-      def call(env)
-        request = env["a2a.request"]
-        source  = @from ? request.public_send(@from) : request
-        id      = source.public_send(@id_field)
-
-        env["a2a.task"] = id.to_s.empty? ? nil : @store.get(id)
-
-        @app.call(env)
+      # Loads a task from the store and places it on `env["a2a.task"]`.
+      # Raises `A2A::TaskNotFoundError` if the task does not exist.
+      #
+      # The task ID is read from the request — by default from `request.id`.
+      # Use `id_field:` to read from a different field, and `from:` to
+      # read from a nested object on the request.
+      #
+      # Not part of the default A2A::Server stack — wrap your agent with it:
+      #
+      #   agent = A2A::Server::Middleware::FetchTaskOrRaise.new(
+      #     A2A.agent { |env| task = env["a2a.task"] },
+      #     store: sqlite_store
+      #   )
+      #
+      class FetchTaskOrRaise
+        def initialize(app, store:, id_field: :id, from: nil)
+          @app      = app
+          @store    = store
+          @id_field = id_field
+          @from     = from
+        end
+
+        def call(env)
+          request = env["a2a.request"]
+          source  = @from ? request.public_send(@from) : request
+          id      = source.public_send(@id_field)
+
+          task = @store.get(id)
+          raise A2A::TaskNotFoundError.new(id) unless task
+
+          env["a2a.task"] = task
+
+          @app.call(env)
+        end
       end
     end
-
-    # Loads a task from the store and places it on `env["a2a.task"]`.
-    # Raises `A2A::TaskNotFoundError` if the task does not exist.
-    #
-    # The task ID is read from the request — by default from `request.id`.
-    # Use `id_field:` to read from a different field, and `from:` to
-    # read from a nested object on the request.
-    #
-    # Usage:
-    #
-    #   on "GetTask" do
-    #     use A2A::Middleware::FetchTaskOrRaise, store: sqlite_store
-    #     respond_with -> (env) {
-    #       task = env["a2a.task"]
-    #     }
-    #   end
-    #
-    #   on "GetTaskPushNotificationConfig" do
-    #     use A2A::Middleware::FetchTaskOrRaise, store: sqlite_store, id_field: :task_id
-    #     respond_with -> (env) { ... }
-    #   end
-    #
-    class FetchTaskOrRaise
-      def initialize(app, store:, id_field: :id, from: nil)
-        @app      = app
-        @store    = store
-        @id_field = id_field
-        @from     = from
-      end
-
-      def call(env)
-        request = env["a2a.request"]
-        source  = @from ? request.public_send(@from) : request
-        id      = source.public_send(@id_field)
-
-        task = @store.get(id)
-        raise A2A::TaskNotFoundError.new(id) unless task
-
-        env["a2a.task"] = task
-
-        @app.call(env)
-      end
-    end
-  end
+end
 end
 
-test do
-  describe "A2A::Middleware::FetchTask" do
+__END__
+  describe "A2A::Server::Middleware::FetchTask" do
     before do
       @store = Object.new
     end
@@ -100,7 +94,7 @@ test do
       request.define_singleton_method(:id) { "t-1" }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTask.new(downstream, store: @store)
+      mw = A2A::Server::Middleware::FetchTask.new(downstream, store: @store)
       env = { "a2a.request" => request }
 
       mw.call(env).should == task_data
@@ -113,7 +107,7 @@ test do
       request.define_singleton_method(:id) { "missing" }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTask.new(downstream, store: @store)
+      mw = A2A::Server::Middleware::FetchTask.new(downstream, store: @store)
       env = { "a2a.request" => request }
 
       mw.call(env).should.be.nil
@@ -124,7 +118,7 @@ test do
       request.define_singleton_method(:id) { "" }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTask.new(downstream, store: @store)
+      mw = A2A::Server::Middleware::FetchTask.new(downstream, store: @store)
       env = { "a2a.request" => request }
 
       mw.call(env).should.be.nil
@@ -138,7 +132,7 @@ test do
       request.define_singleton_method(:message) { message }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTask.new(downstream, store: @store, id_field: :task_id, from: :message)
+      mw = A2A::Server::Middleware::FetchTask.new(downstream, store: @store, id_field: :task_id, from: :message)
       env = { "a2a.request" => request }
 
       mw.call(env).should.be.nil
@@ -155,14 +149,14 @@ test do
       request.define_singleton_method(:message) { message }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTask.new(downstream, store: @store, id_field: :task_id, from: :message)
+      mw = A2A::Server::Middleware::FetchTask.new(downstream, store: @store, id_field: :task_id, from: :message)
       env = { "a2a.request" => request }
 
       mw.call(env).should == task_data
     end
   end
 
-  describe "A2A::Middleware::FetchTaskOrRaise" do
+  describe "A2A::Server::Middleware::FetchTaskOrRaise" do
     before do
       @store = Object.new
     end
@@ -175,7 +169,7 @@ test do
       request.define_singleton_method(:id) { "t-1" }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTaskOrRaise.new(downstream, store: @store)
+      mw = A2A::Server::Middleware::FetchTaskOrRaise.new(downstream, store: @store)
       env = { "a2a.request" => request }
 
       mw.call(env).should == task_data
@@ -188,7 +182,7 @@ test do
       request.define_singleton_method(:id) { "missing" }
 
       downstream = -> (env) { :should_not_reach }
-      mw = A2A::Middleware::FetchTaskOrRaise.new(downstream, store: @store)
+      mw = A2A::Server::Middleware::FetchTaskOrRaise.new(downstream, store: @store)
       env = { "a2a.request" => request }
 
       lambda { mw.call(env) }.should.raise(A2A::TaskNotFoundError)
@@ -202,7 +196,7 @@ test do
       request.define_singleton_method(:task_id) { "t-2" }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTaskOrRaise.new(downstream, store: @store, id_field: :task_id)
+      mw = A2A::Server::Middleware::FetchTaskOrRaise.new(downstream, store: @store, id_field: :task_id)
       env = { "a2a.request" => request }
 
       mw.call(env).should == task_data
@@ -219,10 +213,9 @@ test do
       request.define_singleton_method(:message) { message }
 
       downstream = -> (env) { env["a2a.task"] }
-      mw = A2A::Middleware::FetchTaskOrRaise.new(downstream, store: @store, id_field: :task_id, from: :message)
+      mw = A2A::Server::Middleware::FetchTaskOrRaise.new(downstream, store: @store, id_field: :task_id, from: :message)
       env = { "a2a.request" => request }
 
       mw.call(env).should == task_data
     end
   end
-end

data/lib/a2a/{middleware → server/middleware}/limit_history_length.rb

@@ -4,62 +4,54 @@ require "bundler/setup"
 require "a2a"
 
 module A2A
-  module Middleware
-    # Resolves the effective history length limit and sets
-    # `env["a2a.history_length"]` to an integer.
-    #
-    # The server max is required. The effective limit is the *minimum*
-    # of the client-requested value and the server cap. When the client
-    # doesn't specify a history_length, the server cap is used.
-    #
-    # `env["a2a.history_length"]` is always an Integer (0..max).
-    # The handler applies it unconditionally:
-    #
-    #   result["history"] = task[:history]&.last(limit)
-    #
-    # Usage:
-    #
-    #   on "GetTask" do
-    #     use A2A::Middleware::FetchTaskOrRaise, store: sqlite_store
-    #     use A2A::Middleware::LimitHistoryLength, 20
-    #     respond_with -> (env) {
-    #       task  = env["a2a.task"]
-    #       limit = env["a2a.history_length"]
-    #       # ...
-    #       result["history"] = task[:history]&.last(limit)
-    #     }
-    #   end
-    #
-    class LimitHistoryLength
-      def initialize(app, max)
-        @app = app
-        @max = max
-      end
+  class Server
+    module Middleware
+      # Resolves the effective history length limit and sets
+      # `env["a2a.history_length"]` to an integer.
+      #
+      # The server max is required. The effective limit is the *minimum*
+      # of the client-requested value and the server cap. When the client
+      # doesn't specify a history_length, the server cap is used.
+      #
+      # `env["a2a.history_length"]` is always an Integer (0..max).
+      # The agent applies it unconditionally:
+      #
+      #   result["history"] = task[:history]&.last(limit)
+      #
+      # Part of the A2A::Server middleware stack — the max comes from
+      # `A2A::Server.new(history_length: 20)`.
+      #
+      class LimitHistoryLength
+        def initialize(app, max)
+          @app = app
+          @max = max
+        end
 
-      def call(env)
-        request = env["a2a.request"]
-        limit = @max
+        def call(env)
+          request = env["a2a.request"]
+          limit = @max
 
-        if request.respond_to?(:history_length) && request.history_length
-          limit = [request.history_length.to_i, @max].min
-        end
+          if request.respond_to?(:history_length) && request.history_length
+            limit = [request.history_length.to_i, @max].min
+          end
 
-        env["a2a.history_length"] = limit
+          env["a2a.history_length"] = limit
 
-        @app.call(env)
+          @app.call(env)
+        end
       end
     end
-  end
+end
 end
 
-test do
-  describe "A2A::Middleware::LimitHistoryLength" do
+__END__
+  describe "A2A::Server::Middleware::LimitHistoryLength" do
     it "defaults to server max when client does not specify" do
       request = Object.new
       request.define_singleton_method(:history_length) { nil }
 
       downstream = -> (env) { env["a2a.history_length"] }
-      mw = A2A::Middleware::LimitHistoryLength.new(downstream, 20)
+      mw = A2A::Server::Middleware::LimitHistoryLength.new(downstream, 20)
       env = { "a2a.request" => request }
 
       mw.call(env).should == 20
@@ -70,7 +62,7 @@ test do
       request.define_singleton_method(:history_length) { 5 }
 
       downstream = -> (env) { env["a2a.history_length"] }
-      mw = A2A::Middleware::LimitHistoryLength.new(downstream, 20)
+      mw = A2A::Server::Middleware::LimitHistoryLength.new(downstream, 20)
       env = { "a2a.request" => request }
 
       mw.call(env).should == 5
@@ -81,7 +73,7 @@ test do
       request.define_singleton_method(:history_length) { 100 }
 
       downstream = -> (env) { env["a2a.history_length"] }
-      mw = A2A::Middleware::LimitHistoryLength.new(downstream, 20)
+      mw = A2A::Server::Middleware::LimitHistoryLength.new(downstream, 20)
       env = { "a2a.request" => request }
 
       mw.call(env).should == 20
@@ -92,7 +84,7 @@ test do
       request.define_singleton_method(:history_length) { 0 }
 
       downstream = -> (env) { env["a2a.history_length"] }
-      mw = A2A::Middleware::LimitHistoryLength.new(downstream, 20)
+      mw = A2A::Server::Middleware::LimitHistoryLength.new(downstream, 20)
       env = { "a2a.request" => request }
 
       mw.call(env).should == 0
@@ -103,7 +95,7 @@ test do
       request.define_singleton_method(:history_length) { "3" }
 
       downstream = -> (env) { env["a2a.history_length"] }
-      mw = A2A::Middleware::LimitHistoryLength.new(downstream, 20)
+      mw = A2A::Server::Middleware::LimitHistoryLength.new(downstream, 20)
       env = { "a2a.request" => request }
 
       mw.call(env).should == 3
@@ -114,10 +106,9 @@ test do
       request.define_singleton_method(:history_length) { nil }
 
       downstream = -> (env) { env["a2a.history_length"] }
-      mw = A2A::Middleware::LimitHistoryLength.new(downstream, 10)
+      mw = A2A::Server::Middleware::LimitHistoryLength.new(downstream, 10)
       env = { "a2a.request" => request }
 
       mw.call(env).should.be.kind_of(Integer)
     end
   end
-end

data/lib/a2a/{middleware → server/middleware}/limit_pagination_size.rb

@@ -4,54 +4,49 @@ require "bundler/setup"
 require "a2a"
 
 module A2A
-  module Middleware
-    # Clamps `request.page_size` to a valid range and sets
-    # `env["a2a.page_size"]` for downstream handlers.
-    #
-    # Accepts a single integer — the maximum page size (also used as the
-    # default when the client doesn't specify one). Clamps to [1, max].
-    #
-    # Usage:
-    #
-    #   on "ListTasks" do
-    #     use A2A::Middleware::LimitPaginationSize, 50
-    #     respond_with -> (env) {
-    #       page_size = env["a2a.page_size"]
-    #       # ...
-    #     }
-    #   end
-    #
-    class LimitPaginationSize
-      def initialize(app, max = 100)
-        @app = app
-        @max = max
-      end
+  class Server
+    module Middleware
+      # Clamps `request.page_size` to a valid range and sets
+      # `env["a2a.page_size"]` for the agent.
+      #
+      # Accepts a single integer — the maximum page size (also used as the
+      # default when the client doesn't specify one). Clamps to [1, max].
+      #
+      # Part of the A2A::Server middleware stack — the max comes from
+      # `A2A::Server.new(page_size: 50)`.
+      #
+      class LimitPaginationSize
+        def initialize(app, max = 100)
+          @app = app
+          @max = max
+        end
 
-      def call(env)
-        request = env["a2a.request"]
+        def call(env)
+          request = env["a2a.request"]
 
-        page_size = @max
-        if request.respond_to?(:page_size) && request.page_size
-          ps = request.page_size.to_i
-          page_size = [[ps, 1].max, @max].min
-        end
+          page_size = @max
+          if request.respond_to?(:page_size) && request.page_size
+            ps = request.page_size.to_i
+            page_size = [[ps, 1].max, @max].min
+          end
 
-        env["a2a.page_size"] = page_size
+          env["a2a.page_size"] = page_size
 
-        @app.call(env)
+          @app.call(env)
+        end
       end
     end
-  end
+end
 end
 
-test do
-  describe "A2A::Middleware::LimitPaginationSize" do
+__END__
+  describe "A2A::Server::Middleware::LimitPaginationSize" do
     it "uses max as default page size when not specified by client" do
       request = Object.new
       request.define_singleton_method(:page_size) { nil }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
@@ -63,7 +58,7 @@ test do
       request.define_singleton_method(:page_size) { nil }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream, 25)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream, 25)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
@@ -75,7 +70,7 @@ test do
       request.define_singleton_method(:page_size) { 0 }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
@@ -87,7 +82,7 @@ test do
       request.define_singleton_method(:page_size) { 999 }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
@@ -99,7 +94,7 @@ test do
       request.define_singleton_method(:page_size) { 999 }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream, 50)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream, 50)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
@@ -111,7 +106,7 @@ test do
       request.define_singleton_method(:page_size) { 30 }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
@@ -123,11 +118,10 @@ test do
       request.define_singleton_method(:page_size) { "20" }
 
       downstream = -> (env) { env["a2a.page_size"] }
-      mw = A2A::Middleware::LimitPaginationSize.new(downstream)
+      mw = A2A::Server::Middleware::LimitPaginationSize.new(downstream)
       env = { "a2a.request" => request }
 
       result = mw.call(env)
       result.should == 20
     end
   end
-end