agent2agent 1.0.8 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4242ad33f35042f8b326a6ae26d73a86024cb81b3b79dd894e00b061b68dffd
-  data.tar.gz: 145eafed320e355014100c6544f8b71c6ddd670d58553100055f0566b2609616
+  metadata.gz: fadb35d489fe59b7b010bafd2ee6e94adeb0d3cb0d8c6baa2d05fefcdd449fef
+  data.tar.gz: 1fa489faf0e9f155d56d995bb49f208dbc4e28f9ae3bf84796b0bd4af02264b9
 SHA512:
-  metadata.gz: 996b233809f2451ffb736944c86e16d285962828ee8d5ae0fb533566e8a1afe04eeb64fbeb6f269b61f76263725e5e8a701eae7bf579faa11b711735fab28b70
-  data.tar.gz: 64213c6aa6899a4ccec29e319258379653082a43bee58b77a9e8807b01ef11c3d7fa3cda3cb892264e85a5392a5980ce5adb044bf90a755164c5a995f4720a55
+  metadata.gz: 7ce0595b5f4fbb554306d49fe40588ff16b9036e048012b946930d95143dd3f9f98db62cf7e53c9977b8b0d723e469dbe478aa524ee019da57fd1f29e5b90059
+  data.tar.gz: 8caf8f2af8d3f8becdc7b1404ccaebd0333d05c0452cd68a49b59a0ab419bebed4886b1e8f35c1b7eb131a044cd11f97f5ba1ddc70bbf484f923b8bb55826e1e

data/lib/a2a/agent.rb

@@ -7,17 +7,22 @@ module A2A
   # DSL wrapper that collects operation handlers for an A2A agent.
   #
   # An Agent produces handler objects that conform to the Dispatcher's
-  # duck-type contract (#operations, #call). Register an agent on a
-  # Server the same way you would register a plain handler.
+  # contract (#operations, #call). Register an agent on a Server the
+  # same way you would register a plain handler.
   #
   #   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
   #
-  #     on "GetTask" do |request|
-  #       task = store.get(request.id)
-  #       respond A2A::Schema["Task"].new(task.to_h)
+  #     on "GetTask" do
+  #       respond_with -> (env) {
+  #         task = Task.find_by(id: env["a2a.request"].id)
+  #         raise A2A::TaskNotFoundError.new(env["a2a.request"].id) unless task
+  #         task.to_a2a
+  #       }
   #     end
   #   end
   #
@@ -28,105 +33,89 @@ module A2A
 
     def initialize(&block)
       @handlers = []
-
       instance_eval(&block) if block
     end
 
-    # Register a handler block for one or more A2A operations.
+    # Define a handler stack for one or more A2A operations.
+    #
+    # The block is evaluated at definition time to build the middleware
+    # stack. Use `use` to add middleware, `respond_with` to set the
+    # terminal handler.
     #
-    # Operations are identified by their proto name (e.g. "SendMessage",
-    # "GetTask", "CancelTask"). See A2A::Proto.operations for the full list.
+    #   on "SendMessage" do
+    #     use SomeMiddleware
+    #     respond_with -> (env) { ... }
+    #   end
     #
     def on(*operations, &block)
       raise ArgumentError, "on requires at least one operation" if operations.empty?
       raise ArgumentError, "on requires a block" unless block
 
+      builder = StackBuilder.new
+      builder.instance_eval(&block)
+
       handler = Handler.new(
-        agent:      self,
         operations: operations.flatten,
-        block:      block
+        app:        builder.to_app
       )
 
       @handlers << handler
       handler
     end
 
-    # Internal handler object produced by the #on DSL method.
-    # Conforms to the Dispatcher duck-type: #operations, #call.
-    class Handler
-      attr_reader :operations
-
-      def initialize(agent:, operations:, block:)
-        @agent      = agent
-        @operations = operations
-        @block      = block
+    # Builds a per-operation middleware stack.
+    # Collects `use` and `respond_with` calls, compiles into a callable app.
+    class StackBuilder
+      def initialize
+        @middleware = []
+        @terminal   = nil
       end
 
-      def call(env)
-        Context.new(env).execute(&@block)
+      def use(middleware, *args, &block)
+        @middleware << [middleware, args, block]
       end
-    end
 
-    # Execution context for handler blocks.
-    # Provides helper methods so blocks can call store, respond, stream, etc.
-    # directly without holding a reference to the env hash.
-    class Context
-      def initialize(env)
-        @env = env
+      def respond_with(callable)
+        @terminal = callable
       end
 
-      def execute(&block)
-        instance_exec(@env["a2a.request"], &block)
-      end
+      def to_app
+        raise ArgumentError, "respond_with is required" unless @terminal
 
-      def store
-        @env["a2a.store"]
-      end
+        app = Terminal.new(@terminal)
 
-      def request
-        @env["a2a.request"]
+        @middleware.reverse_each do |klass, args, block|
+          app = klass.new(app, *args, &block)
+        end
+
+        app
       end
+    end
 
-      def agent_card
-        @env["a2a.agent_card"]
+    # Wraps the respond_with lambda as a callable.
+    # Returns whatever the lambda returns.
+    class Terminal
+      def initialize(callable)
+        @callable = callable
       end
 
-      def respond(result)
-        @env["a2a.result"] = result
+      def call(env)
+        @callable.call(env)
       end
+    end
 
-      # Create an SSE stream for streaming responses.
-      #
-      # Automatically selects the right stream type based on the binding:
-      #   - JSON-RPC binding -> JsonRpcStream (wraps events in envelopes)
-      #   - REST binding     -> RestStream (bare JSON events)
-      #
-      # The stream is registered on env["a2a.stream"] so the binding
-      # middleware returns it as the Rack body. Falcon streams it natively
-      # via Protocol::HTTP::Body::Writable — no threads, no polling.
-      #
-      # Usage in a handler block:
-      #
-      #   on "SendStreamingMessage" do |request|
-      #     s = stream
-      #     Async do
-      #       s.event({ "task" => { ... } })
-      #       s.event({ "statusUpdate" => { ... } })
-      #       s.finish
-      #     end
-      #   end
-      #
-      def stream
-        require "a2a/sse"
+    # Handler object produced by the #on DSL method.
+    # Conforms to the Dispatcher contract: #operations, #call.
+    class Handler
+      attr_reader :operations
 
-        s = if @env["a2a.json_rpc_id"]
-          A2A::SSE::JsonRpcStream.new(json_rpc_id: @env["a2a.json_rpc_id"])
-        else
-          A2A::SSE::RestStream.new
-        end
+      def initialize(operations:, app:)
+        @operations = operations
+        @app        = app
+      end
 
-        @env["a2a.stream"] = s
-        s
+      def call(env)
+        @app.call(env)
       end
     end
   end
@@ -136,8 +125,8 @@ test do
   describe "A2A::Agent" do
     it "registers handlers via the on DSL" do
       agent = A2A::Agent.new do
-        on "SendMessage" do |request|
-          # no-op
+        on "SendMessage" do
+          respond_with -> (env) { :ok }
         end
       end
 
@@ -147,8 +136,8 @@ test do
 
     it "registers multiple operations on a single handler" do
       agent = A2A::Agent.new do
-        on "SendMessage", "GetTask" do |request|
-          # no-op
+        on "SendMessage", "GetTask" do
+          respond_with -> (env) { :ok }
         end
       end
 
@@ -158,7 +147,9 @@ test do
     it "raises if on is called without operations" do
       lambda {
         A2A::Agent.new do
-          on do |request|; end
+          on do
+            respond_with -> (env) { :ok }
+          end
         end
       }.should.raise(ArgumentError)
     end
@@ -170,74 +161,131 @@ test do
       }.should.raise(ArgumentError)
     end
 
-    it "executes handler block in Context with access to env" do
+    it "raises if respond_with is not provided" do
+      lambda {
+        A2A::Agent.new do
+          on "SendMessage" do
+            use Class.new
+          end
+        end
+      }.should.raise(ArgumentError)
+    end
+
+    it "returns the respond_with lambda result" do
       agent = A2A::Agent.new do
-        on "SendMessage" do |request|
-          respond({ "echo" => true })
+        on "SendMessage" do
+          respond_with -> (env) { { "echo" => true } }
         end
       end
 
-      env = {
-        "a2a.store"      => A2A::TaskStore.new,
-        "a2a.request"    => { "message" => "hello" },
-        "a2a.agent_card" => { "name" => "Test" },
-      }
+      env = { "a2a.request" => {} }
+      result = agent.handlers.first.call(env)
+      result.should == { "echo" => true }
+    end
 
-      agent.handlers.first.call(env)
+    it "returns a Schema::Definition from respond_with" do
+      schema_obj = A2A::Schema["Task"].new(
+        "id"        => "t-1",
+        "contextId" => "c-1",
+        "status"    => { "state" => "TASK_STATE_COMPLETED", "timestamp" => "2025-01-01T00:00:00.000Z" },
+      )
+
+      agent = A2A::Agent.new do
+        on "GetTask" do
+          respond_with -> (env) { schema_obj }
+        end
+      end
 
-      env["a2a.result"].should == { "echo" => true }
+      env = { "a2a.request" => {} }
+      result = agent.handlers.first.call(env)
+      result.should == schema_obj
     end
 
-    it "provides store access in handler context" do
-      store = A2A::TaskStore.new
-      seen_store = nil
+    it "passes env to the respond_with lambda" do
+      seen_env = nil
 
       agent = A2A::Agent.new do
-        on "SendMessage" do |request|
-          seen_store = store
+        on "SendMessage" do
+          respond_with -> (env) { seen_env = env; :ok }
         end
       end
 
-      env = { "a2a.store" => store, "a2a.request" => {} }
+      env = { "a2a.request" => { "msg" => "hi" } }
       agent.handlers.first.call(env)
-
-      seen_store.should == store
+      seen_env.should == env
     end
 
-    it "creates a JsonRpcStream when JSON-RPC binding is active" do
+    it "executes middleware in order" do
+      order = []
+
+      mw1 = Class.new do
+        define_method(:initialize) { |app| @app = app }
+        define_method(:call) { |env| order << :mw1; @app.call(env) }
+      end
+
+      mw2 = Class.new do
+        define_method(:initialize) { |app| @app = app }
+        define_method(:call) { |env| order << :mw2; @app.call(env) }
+      end
+
       agent = A2A::Agent.new do
-        on "SendStreamingMessage" do |request|
-          s = stream
-          s.is_a?(A2A::SSE::JsonRpcStream).should == true
+        on "SendMessage" do
+          use mw1
+          use mw2
+          respond_with -> (env) { order << :terminal; :done }
         end
       end
 
-      env = {
-        "a2a.store"       => A2A::TaskStore.new,
-        "a2a.request"     => {},
-        "a2a.json_rpc_id" => 42,
-      }
+      env = { "a2a.request" => {} }
       agent.handlers.first.call(env)
+      order.should == [:mw1, :mw2, :terminal]
+    end
 
-      env["a2a.stream"].should.not.be.nil
-      env["a2a.stream"].is_a?(Protocol::HTTP::Body::Readable).should == true
+    it "middleware can intercept and return early" do
+      blocker = Class.new do
+        define_method(:initialize) { |app| @app = app }
+        define_method(:call) { |env| :blocked }
+      end
+
+      agent = A2A::Agent.new do
+        on "SendMessage" do
+          use blocker
+          respond_with -> (env) { :should_not_reach }
+        end
+      end
+
+      env = { "a2a.request" => {} }
+      result = agent.handlers.first.call(env)
+      result.should == :blocked
     end
 
-    it "creates a RestStream when REST binding is active" do
+    # ── Error behavior ─────────────────────────────────────────────────
+    # Errors propagate to the Dispatcher which catches them.
+
+    it "lets A2A::Error propagate (Dispatcher catches it)" do
       agent = A2A::Agent.new do
-        on "SendStreamingMessage" do |request|
-          s = stream
-          s.is_a?(A2A::SSE::RestStream).should == true
+        on "GetTask" do
+          respond_with -> (env) {
+            raise A2A::TaskNotFoundError.new("task-abc")
+          }
         end
       end
 
-      env = {
-        "a2a.store"   => A2A::TaskStore.new,
-        "a2a.request" => {},
-      }
-      agent.handlers.first.call(env)
+      env = { "a2a.request" => {} }
+      lambda { agent.handlers.first.call(env) }.should.raise(A2A::TaskNotFoundError)
+    end
+
+    it "lets unexpected errors propagate" do
+      agent = A2A::Agent.new do
+        on "SendMessage" do
+          respond_with -> (env) {
+            raise RuntimeError, "unexpected bug"
+          }
+        end
+      end
 
-      env["a2a.stream"].should.not.be.nil
+      env = { "a2a.request" => {} }
+      lambda { agent.handlers.first.call(env) }.should.raise(RuntimeError)
     end
   end
 end