agent2agent 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fadb35d489fe59b7b010bafd2ee6e94adeb0d3cb0d8c6baa2d05fefcdd449fef
-  data.tar.gz: 1fa489faf0e9f155d56d995bb49f208dbc4e28f9ae3bf84796b0bd4af02264b9
+  metadata.gz: dcbe8b4376828c18b601b4ed92a16afc7adc63db6ebb3354b144d1510c0a91bb
+  data.tar.gz: '096dd66beddb0b01c21fb8fa631318cb202a8abde4cc475de1c05fd3327cdbb3'
 SHA512:
-  metadata.gz: 7ce0595b5f4fbb554306d49fe40588ff16b9036e048012b946930d95143dd3f9f98db62cf7e53c9977b8b0d723e469dbe478aa524ee019da57fd1f29e5b90059
-  data.tar.gz: 8caf8f2af8d3f8becdc7b1404ccaebd0333d05c0452cd68a49b59a0ab419bebed4886b1e8f35c1b7eb131a044cd11f97f5ba1ddc70bbf484f923b8bb55826e1e
+  metadata.gz: d5ff820324edc012ed3c6f417187afe73381572cfa078a226bebe770a88d21330eec4df404d4f0080f340900e51044999ec0c685ae278f259d38e6da80e51223
+  data.tar.gz: 4c2fb80eb26b98ad58003599e3f8d87fc864876d10f4c007b6c1fb473225883b3d2a288a806ebd7fd5a3f1917fe193dec8f0cf6682cfd0334261c140ed384a7f

data/lib/a2a/agent.rb

@@ -1,291 +1,148 @@
 # frozen_string_literal: true
 
 require "bundler/setup"
+require "console"
 require "a2a"
 
 module A2A
-  # DSL wrapper that collects operation handlers for an A2A agent.
+  # Builds a complete A2A server (a rack app) from a handler block —
+  # the one-call entrypoint.
   #
-  # An Agent produces handler objects that conform to the Dispatcher's
-  # contract (#operations, #call). Register an agent on a Server the
-  # same way you would register a plain handler.
+  # The block receives the rack env and returns a domain object
+  # (A2A::Protocol::JsonSchema::Definition) — the binding layer formats
+  # it into HTTP. Route operations with pattern matching:
   #
-  #   agent = A2A::Agent.new do
-  #     on "SendMessage" do
-  #       respond_with -> (env) {
-  #         A2A::Schema["Send Message Response"].new({})
-  #       }
+  #   run A2A.agent(agent_card: { "name" => "My Agent" }) do |env|
+  #     case env["a2a.operation"]
+  #     in "SendMessage"
+  #       A2A::Protocol::JsonSchema["Send Message Response"].new({})
+  #     in "GetTask"
+  #       task = Task.find_by(id: env["a2a.request"].id)
+  #       raise A2A::TaskNotFoundError.new(env["a2a.request"].id) unless task
+  #       task.to_a2a
   #     end
+  #   end
   #
-  #     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
+  # To route on request contents as well, match a tuple — Definition
+  # implements deconstruct_keys, so patterns destructure recursively:
+  #
+  #   case [env["a2a.operation"], env["a2a.request"]]
+  #   in ["SendMessage", { message: { task_id: String => id } }] if !id.empty?
+  #     # continuation of task `id`
+  #   in ["SendMessage", _]
+  #     # new task
   #   end
   #
-  #   server.register(agent)
+  def self.agent(**options, &block) = Server.new(**options, &block)
+
+  # Wraps the agent block with the server's error boundary:
+  #
+  #   NoMatchingPatternError -> A2A::UnsupportedOperationError, so an
+  #     unhandled operation falls out of `case ... in` with no else branch
+  #   A2A::Error             -> returned for the binding layer to format
+  #   anything else          -> logged, returned as a JSON-RPC internal error
   #
   class Agent
-    attr_reader :handlers
-
     def initialize(&block)
-      @handlers = []
-      instance_eval(&block) if block
-    end
-
-    # 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.
-    #
-    #   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(
-        operations: operations.flatten,
-        app:        builder.to_app
-      )
-
-      @handlers << handler
-      handler
-    end
-
-    # 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 use(middleware, *args, &block)
-        @middleware << [middleware, args, block]
-      end
-
-      def respond_with(callable)
-        @terminal = callable
-      end
+      raise ArgumentError, "agent requires a block" unless block
 
-      def to_app
-        raise ArgumentError, "respond_with is required" unless @terminal
-
-        app = Terminal.new(@terminal)
-
-        @middleware.reverse_each do |klass, args, block|
-          app = klass.new(app, *args, &block)
-        end
-
-        app
-      end
-    end
-
-    # Wraps the respond_with lambda as a callable.
-    # Returns whatever the lambda returns.
-    class Terminal
-      def initialize(callable)
-        @callable = callable
-      end
-
-      def call(env)
-        @callable.call(env)
-      end
+      @block = block
     end
 
-    # Handler object produced by the #on DSL method.
-    # Conforms to the Dispatcher contract: #operations, #call.
-    class Handler
-      attr_reader :operations
-
-      def initialize(operations:, app:)
-        @operations = operations
-        @app        = app
-      end
-
-      def call(env)
-        @app.call(env)
-      end
+    def call(env)
+      @block.call(env)
+    rescue NoMatchingPatternError
+      A2A::UnsupportedOperationError.new(
+        message: "Operation not supported: #{env["a2a.operation"]}"
+      )
+    rescue A2A::Error => e
+      e
+    rescue => e
+      Console.error(self, "Agent raised #{e.class}: #{e.message}", e)
+      A2A::Error.new("Internal error", code: -32603, http_status: 500)
     end
   end
 end
 
-test do
-  describe "A2A::Agent" do
-    it "registers handlers via the on DSL" do
-      agent = A2A::Agent.new do
-        on "SendMessage" do
-          respond_with -> (env) { :ok }
-        end
-      end
-
-      agent.handlers.length.should == 1
-      agent.handlers.first.operations.should == ["SendMessage"]
-    end
-
-    it "registers multiple operations on a single handler" do
-      agent = A2A::Agent.new do
-        on "SendMessage", "GetTask" do
-          respond_with -> (env) { :ok }
-        end
-      end
-
-      agent.handlers.first.operations.should == ["SendMessage", "GetTask"]
-    end
-
-    it "raises if on is called without operations" do
-      lambda {
-        A2A::Agent.new do
-          on do
-            respond_with -> (env) { :ok }
-          end
-        end
-      }.should.raise(ArgumentError)
-    end
-
-    it "raises if on is called without a block" do
-      lambda {
-        agent = A2A::Agent.new
-        agent.on "SendMessage"
-      }.should.raise(ArgumentError)
+__END__
+  describe "A2A.agent" do
+    it "returns an A2A::Server" do
+      server = A2A.agent(agent_card: { "name" => "Test" }) { |env| nil }
+      server.should.be.is_a(A2A::Server)
     end
+  end
 
-    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)
+  describe "A2A::Agent" do
+    it "requires a block" do
+      lambda { A2A::Agent.new }.should.raise(ArgumentError)
     end
 
-    it "returns the respond_with lambda result" do
-      agent = A2A::Agent.new do
-        on "SendMessage" do
-          respond_with -> (env) { { "echo" => true } }
-        end
-      end
-
-      env = { "a2a.request" => {} }
-      result = agent.handlers.first.call(env)
-      result.should == { "echo" => true }
+    it "calls the block with env and returns its result" do
+      agent = A2A::Agent.new { |env| env["a2a.operation"] }
+      agent.call({ "a2a.operation" => "SendMessage" }).should == "SendMessage"
     end
 
-    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 }
+    it "routes operations with pattern matching" do
+      agent = A2A::Agent.new do |env|
+        case env["a2a.operation"]
+        in "SendMessage" then :sent
+        in "GetTask" then :got
         end
       end
 
-      env = { "a2a.request" => {} }
-      result = agent.handlers.first.call(env)
-      result.should == schema_obj
+      agent.call({ "a2a.operation" => "SendMessage" }).should == :sent
+      agent.call({ "a2a.operation" => "GetTask" }).should == :got
     end
 
-    it "passes env to the respond_with lambda" do
-      seen_env = nil
-
-      agent = A2A::Agent.new do
-        on "SendMessage" do
-          respond_with -> (env) { seen_env = env; :ok }
+    it "returns UnsupportedOperationError when no pattern matches" do
+      agent = A2A::Agent.new do |env|
+        case env["a2a.operation"]
+        in "SendMessage" then :sent
         end
       end
 
-      env = { "a2a.request" => { "msg" => "hi" } }
-      agent.handlers.first.call(env)
-      seen_env.should == env
+      result = agent.call({ "a2a.operation" => "UnknownOp" })
+      result.should.be.is_a(A2A::UnsupportedOperationError)
+      result.code.should == -32004
     end
 
-    it "executes middleware in order" do
-      order = []
+    it "returns A2A::Error when the block raises one" do
+      agent = A2A::Agent.new { |env| raise A2A::TaskNotFoundError.new("t-1") }
 
-      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 "SendMessage" do
-          use mw1
-          use mw2
-          respond_with -> (env) { order << :terminal; :done }
-        end
-      end
-
-      env = { "a2a.request" => {} }
-      agent.handlers.first.call(env)
-      order.should == [:mw1, :mw2, :terminal]
+      result = agent.call({})
+      result.should.be.is_a(A2A::TaskNotFoundError)
+      result.code.should == -32001
     end
 
-    it "middleware can intercept and return early" do
-      blocker = Class.new do
-        define_method(:initialize) { |app| @app = app }
-        define_method(:call) { |env| :blocked }
-      end
+    it "returns internal error when the block raises unexpectedly" do
+      agent = A2A::Agent.new { |env| raise "boom" }
 
-      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
+      result = agent.call({})
+      result.should.be.is_a(A2A::Error)
+      result.code.should == -32603
+      result.http_status.should == 500
     end
 
-    # ── 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 "GetTask" do
-          respond_with -> (env) {
-            raise A2A::TaskNotFoundError.new("task-abc")
-          }
+    it "matches request contents via deconstruct_keys" do
+      agent = A2A::Agent.new do |env|
+        case [env["a2a.operation"], env["a2a.request"]]
+        in ["SendMessage", { message: { task_id: String => id } }] if !id.empty?
+          [:continuation, id]
+        in ["SendMessage", _]
+          :new_task
         end
       end
 
-      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
+      request = A2A::Protocol::JsonSchema["Send Message Request"].new(
+        message: { "taskId" => "t-1", "role" => "ROLE_USER" }
+      )
+      agent.call({ "a2a.operation" => "SendMessage", "a2a.request" => request })
+        .should == [:continuation, "t-1"]
 
-      env = { "a2a.request" => {} }
-      lambda { agent.handlers.first.call(env) }.should.raise(RuntimeError)
+      request = A2A::Protocol::JsonSchema["Send Message Request"].new(
+        message: { "role" => "ROLE_USER" }
+      )
+      agent.call({ "a2a.operation" => "SendMessage", "a2a.request" => request })
+        .should == :new_task
     end
   end
-end

data/lib/a2a/{faraday → client}/middleware/json_rpc/request.rb

@@ -5,7 +5,7 @@ require "a2a"
 require "faraday"
 
 module A2A
-  module Faraday
+  class Client
     module Middleware
       module JsonRpc
         # Faraday request middleware that wraps the request body in a
@@ -19,7 +19,8 @@ module A2A
             operation = env.request.context&.dig(:a2a_operation)
             return unless operation
 
-            env.url.path = "/a2a"
+            # POST to the server's mount root — env.url already carries the
+            # base path (e.g. "/agent1" when mounted at a subpath).
             env.method = :post
 
             env.body = {
@@ -41,13 +42,14 @@ module A2A
   end
 end
 
-::Faraday::Request.register_middleware(a2a_json_rpc: A2A::Faraday::Middleware::JsonRpc::Request)
+::Faraday::Request.register_middleware(a2a_json_rpc: A2A::Client::Middleware::JsonRpc::Request)
 
-test do
-  middleware = A2A::Faraday::Middleware::JsonRpc::Request
-  operation = A2A::Proto.operation("SendMessage")
+__END__
+describe "A2A::Client::Middleware::JsonRpc::Request" do
+  middleware = A2A::Client::Middleware::JsonRpc::Request
+  operation = A2A::Protocol::Protobuf.operation("SendMessage")
 
-  it "wraps body in JSON-RPC 2.0 envelope and sets path to /a2a" do
+  it "wraps body in JSON-RPC 2.0 envelope and sets path to /" do
     env = ::Faraday::Env.new
     env.url = URI.parse("http://localhost:9292/")
     env.body = { "message" => { "role" => "ROLE_USER" } }
@@ -56,7 +58,7 @@ test do
 
     middleware.new(nil).on_request(env)
 
-    env.url.path.should == "/a2a"
+    env.url.path.should == "/"
     env.method.should == :post
     env.body[:jsonrpc].should == "2.0"
     env.body[:id].should == 1

data/lib/a2a/{faraday → client}/middleware/json_rpc/response.rb

@@ -6,11 +6,11 @@ require "faraday"
 require "json"
 
 module A2A
-  module Faraday
+  class Client
     module Middleware
       module JsonRpc
         # Faraday response middleware that unwraps JSON-RPC 2.0 responses
-        # and converts the result into A2A::Schema::Definition objects.
+        # and converts the result into A2A::Protocol::JsonSchema::Definition objects.
         #
         # Reads env.request.context[:a2a_operation] to determine which
         # Schema class to instantiate. If no operation is set, passes through.
@@ -55,11 +55,12 @@ module A2A
   end
 end
 
-::Faraday::Response.register_middleware(a2a_json_rpc: A2A::Faraday::Middleware::JsonRpc::Response)
+::Faraday::Response.register_middleware(a2a_json_rpc: A2A::Client::Middleware::JsonRpc::Response)
 
-test do
-  middleware = A2A::Faraday::Middleware::JsonRpc::Response
-  operation = A2A::Proto.operation("GetTask")
+__END__
+describe "A2A::Client::Middleware::JsonRpc::Response" do
+  middleware = A2A::Client::Middleware::JsonRpc::Response
+  operation = A2A::Protocol::Protobuf.operation("GetTask")
 
   it "unwraps JSON-RPC result into Schema object" do
     env = ::Faraday::Env.new
@@ -75,7 +76,7 @@ test do
 
     middleware.new(nil).on_complete(env)
 
-    env.body.should.be.kind_of(A2A::Schema::Definition)
+    env.body.should.be.kind_of(A2A::Protocol::JsonSchema::Definition)
     env.body.id.should == "task-123"
     env.body.context_id.should == "ctx-456"
   end
@@ -93,7 +94,7 @@ test do
   end
 
   it "returns raw hash when response_schema is nil" do
-    op = A2A::Proto.operation("DeleteTaskPushNotificationConfig")
+    op = A2A::Protocol::Protobuf.operation("DeleteTaskPushNotificationConfig")
     env = ::Faraday::Env.new
     env.body = { "jsonrpc" => "2.0", "id" => 1, "result" => {} }
     env.request = ::Faraday::RequestOptions.new
@@ -125,7 +126,7 @@ test do
 
     middleware.new(nil).on_complete(env)
 
-    env.body.should.be.kind_of(A2A::Schema::Definition)
+    env.body.should.be.kind_of(A2A::Protocol::JsonSchema::Definition)
     env.body.id.should == "task-1"
   end
 end

data/lib/a2a/{faraday → client}/middleware/rest/request.rb

@@ -5,7 +5,7 @@ require "a2a"
 require "faraday"
 
 module A2A
-  module Faraday
+  class Client
     module Middleware
       module REST
         # Faraday request middleware that rewrites the request for the
@@ -13,8 +13,9 @@ module A2A
         #
         # Reads env.request.context[:a2a_operation] to determine the
         # HTTP verb and path. Interpolates path parameters from the
-        # request body (e.g. {id=*} placeholders). For GET/DELETE
-        # operations, remaining params become query string parameters.
+        # request body (e.g. {id=*} placeholders) and prefixes the
+        # /rest mount point. For GET/DELETE operations, remaining
+        # params become query string parameters.
         #
         # Sets Content-Type to application/a2a+json for POST requests.
         #
@@ -27,14 +28,22 @@ module A2A
             path = interpolate_path(operation.rest_path, params)
             remaining = remove_path_params(operation.rest_path, params)
 
-            env.url.path = path
+            # Prefix /rest under the base path, so servers mounted at a
+            # subpath (e.g. "/agent1") keep working.
+            env.url.path = "#{env.url.path.chomp("/")}/rest#{path}"
             env.method = operation.rest_verb.to_sym
 
             if [:get, :delete].include?(env.method)
-              remaining.each { |k, v| env.params[k.to_s] = v }
+              # The URL is already built by the time request middleware runs,
+              # so query params must be encoded into env.url directly —
+              # env.params is not consulted after this point.
+              env.url.query = URI.encode_www_form(remaining) unless remaining.empty?
               env.body = nil
             else
-              env.body = remaining
+              # Serialize to JSON here rather than relying on Faraday's
+              # built-in :json middleware, which only recognizes
+              # application/json and application/vnd.*+json content types.
+              env.body = remaining.is_a?(String) ? remaining : JSON.generate(remaining)
               env.request_headers["content-type"] = "application/a2a+json"
             end
           end
@@ -76,13 +85,14 @@ module A2A
   end
 end
 
-::Faraday::Request.register_middleware(a2a_rest: A2A::Faraday::Middleware::REST::Request)
+::Faraday::Request.register_middleware(a2a_rest: A2A::Client::Middleware::REST::Request)
 
-test do
-  middleware = A2A::Faraday::Middleware::REST::Request
+__END__
+describe "A2A::Client::Middleware::REST::Request" do
+  middleware = A2A::Client::Middleware::REST::Request
 
   it "rewrites POST operation with correct path, verb, and content-type" do
-    operation = A2A::Proto.operation("SendMessage")
+    operation = A2A::Protocol::Protobuf.operation("SendMessage")
     env = ::Faraday::Env.new
     env.url = URI.parse("http://localhost:9292/")
     env.body = { "message" => { "role" => "ROLE_USER" } }
@@ -93,14 +103,14 @@ test do
 
     middleware.new(nil).on_request(env)
 
-    env.url.path.should == "/message:send"
+    env.url.path.should == "/rest/message:send"
     env.method.should == :post
-    env.body.should == { "message" => { "role" => "ROLE_USER" } }
+    JSON.parse(env.body).should == { "message" => { "role" => "ROLE_USER" } }
     env.request_headers["content-type"].should == "application/a2a+json"
   end
 
   it "rewrites GET operation with path interpolation and query params" do
-    operation = A2A::Proto.operation("GetTask")
+    operation = A2A::Protocol::Protobuf.operation("GetTask")
     env = ::Faraday::Env.new
     env.url = URI.parse("http://localhost:9292/")
     env.body = { "id" => "task-123", "historyLength" => "5" }
@@ -111,14 +121,14 @@ test do
 
     middleware.new(nil).on_request(env)
 
-    env.url.path.should == "/tasks/task-123"
+    env.url.path.should == "/rest/tasks/task-123"
     env.method.should == :get
     env.body.should.be.nil
-    env.params["historyLength"].should == "5"
+    env.url.query.should == "historyLength=5"
   end
 
   it "rewrites DELETE operation with multi-param path interpolation" do
-    operation = A2A::Proto.operation("DeleteTaskPushNotificationConfig")
+    operation = A2A::Protocol::Protobuf.operation("DeleteTaskPushNotificationConfig")
     env = ::Faraday::Env.new
     env.url = URI.parse("http://localhost:9292/")
     env.body = { "taskId" => "task-123", "id" => "config-1" }
@@ -129,13 +139,13 @@ test do
 
     middleware.new(nil).on_request(env)
 
-    env.url.path.should == "/tasks/task-123/pushNotificationConfigs/config-1"
+    env.url.path.should == "/rest/tasks/task-123/pushNotificationConfigs/config-1"
     env.method.should == :delete
     env.body.should.be.nil
   end
 
   it "rewrites POST cancel with path interpolation" do
-    operation = A2A::Proto.operation("CancelTask")
+    operation = A2A::Protocol::Protobuf.operation("CancelTask")
     env = ::Faraday::Env.new
     env.url = URI.parse("http://localhost:9292/")
     env.body = { "id" => "task-123", "metadata" => { "key" => "val" } }
@@ -146,9 +156,9 @@ test do
 
     middleware.new(nil).on_request(env)
 
-    env.url.path.should == "/tasks/task-123:cancel"
+    env.url.path.should == "/rest/tasks/task-123:cancel"
     env.method.should == :post
-    env.body.should == { "metadata" => { "key" => "val" } }
+    JSON.parse(env.body).should == { "metadata" => { "key" => "val" } }
   end
 
   it "passes through when no operation is set" do