agent2agent 1.0.0

data/lib/a2a/server/list_tasks.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  module Server
+    class ListTasks
+      def call(env)
+        env["a2a.result"] = Schema["List Tasks Response"].new({})
+      end
+    end
+  end
+end

data/lib/a2a/server/send_message.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  module Server
+    class SendMessage
+      def call(env)
+        env["a2a.result"] = Schema["Send Message Response"].new({})
+      end
+    end
+  end
+end

data/lib/a2a/server/send_streaming_message.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  module Server
+    class SendStreamingMessage
+      def call(env)
+        env["a2a.result"] = Schema["Stream Response"].new({})
+      end
+    end
+  end
+end

data/lib/a2a/server/subscribe_to_task.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  module Server
+    class SubscribeToTask
+      def call(env)
+        env["a2a.result"] = Schema["Stream Response"].new({})
+      end
+    end
+  end
+end

data/lib/a2a/server/triage.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  class Server
+    # Rack middleware that resolves which A2A operation a request targets.
+    #
+    # 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.
+    #
+    # Env keys read:
+    #   "a2a.json_rpc_method" — set by Bindings::JsonRpc
+    #   "a2a.verb"            — set by Bindings::Rest
+    #   "a2a.path"            — set by Bindings::Rest
+    #   "a2a.body"            — set by either binding
+    #
+    # Env keys set:
+    #   "a2a.operation"       — operation name string (e.g. "SendMessage")
+    #   "a2a.proto_operation" — Proto::Operation instance
+    #   "a2a.request"         — Schema::Definition instance (validated request)
+    #
+    class Triage
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        op = resolve_operation(env)
+
+        unless op
+          return [404, { "content-type" => "text/plain" }, ["Unknown operation"]]
+        end
+
+        env["a2a.operation"]       = op.name
+        env["a2a.proto_operation"] = op
+
+        body = env["a2a.body"] || {}
+
+        # For REST, merge extracted path params into the body.
+        if env["a2a.path"]
+          path_params = extract_path_params(op.rest_path, env["a2a.path"])
+          body = body.merge(path_params)
+        end
+
+        if op.request_schema
+          env["a2a.request"] = op.request_schema.new(body)
+        end
+
+        @app.call(env)
+      end
+
+      private
+
+        def resolve_operation(env)
+          if env["a2a.json_rpc_method"]
+            Proto.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|
+            op.http_bindings.any? do |b|
+              b.verb == verb && path_matches?(b.path, path)
+            end
+          end
+        end
+
+        # Match a proto path pattern like "/tasks/{id=*}" against
+        # an actual request path like "/tasks/abc-123".
+        def path_matches?(pattern, path)
+          regex = pattern_to_regex(pattern)
+          path.match?(regex)
+        end
+
+        def pattern_to_regex(pattern)
+          re = pattern.gsub(/\{[^}]+\}/, '([^/]+)')
+          /\A#{re}\z/
+        end
+
+        def extract_path_params(pattern, path)
+          names = pattern.scan(/\{(\w+)(?:=[^}]*)?\}/).flatten
+          regex = pattern_to_regex(pattern)
+          match = path.match(regex)
+          return {} unless match
+
+          names.zip(match.captures).to_h
+        end
+    end
+  end
+end

data/lib/a2a/server.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+require "a2a/server/env"
+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:
+  #
+  #   /.well-known/agent-card.json
+  #     → Env → serve agent card
+  #
+  #   /a2a  (JSON-RPC 2.0)
+  #     → Env → Bindings::JsonRpc → Triage → Dispatcher
+  #
+  #   /     (HTTP+JSON/REST)
+  #     → Env → Bindings::Rest → Triage → Dispatcher
+  #
+  # Usage:
+  #
+  #   agent = A2A::Agent.new do
+  #     on "SendMessage" do |request|
+  #       respond A2A::Schema["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: {}, store: TaskStore.new)
+      @agent_card = agent_card
+      @store      = store
+      @dispatcher = Dispatcher.new
+      @app        = build_app
+    end
+
+    # 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
+    end
+
+    def call(env)
+      @app.call(env)
+    end
+
+    private
+
+      def build_app
+        require "a2a/bindings/json_rpc"
+        require "a2a/bindings/rest"
+
+        agent_card = @agent_card
+        store      = @store
+        dispatcher = @dispatcher
+
+        Rack::Builder.app do
+          use A2A::Server::Env, agent_card: agent_card, store: store
+
+          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::Bindings::JsonRpc
+            use A2A::Server::Triage
+            run dispatcher
+          end
+
+          map "/" do
+            use A2A::Bindings::Rest
+            use A2A::Server::Triage
+            run dispatcher
+          end
+        end
+      end
+  end
+end

data/lib/a2a/sse/json_rpc_stream.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "stream"
+
+module A2A
+  module SSE
+    # SSE stream that wraps each event in a JSON-RPC 2.0 response envelope.
+    #
+    # Per the A2A spec, JSON-RPC streaming returns SSE where each `data:` line
+    # is a full JSON-RPC response: {"jsonrpc":"2.0","id":N,"result":{...}}
+    #
+    # Usage:
+    #
+    #   stream = A2A::SSE::JsonRpcStream.new(json_rpc_id: 1)
+    #
+    #   Async do
+    #     stream.event({ "task" => { ... } })
+    #     stream.finish
+    #   end
+    #
+    #   [200, A2A::SSE::Stream.headers, stream]
+    #
+    class JsonRpcStream < Stream
+      def initialize(json_rpc_id:, **options)
+        @json_rpc_id = json_rpc_id
+        super(**options)
+      end
+
+      # Emit an SSE event wrapped in a JSON-RPC envelope.
+      #
+      # @param data [Hash] the StreamResponse payload (becomes "result")
+      #
+      def event(data, **opts)
+        envelope = {
+          "jsonrpc" => "2.0",
+          "id"      => @json_rpc_id,
+          "result"  => data.respond_to?(:to_h) ? data.to_h : data,
+        }
+        super(envelope, **opts)
+      end
+    end
+  end
+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.event({ "task" => { "id" => "t1" } })
+      stream.finish
+
+      chunk = stream.read
+      chunk.should.include('"jsonrpc"')
+      chunk.should.include('"2.0"')
+      chunk.should.include('"id":42')  # numeric id preserved
+      chunk.should.include('"result"')
+    end
+
+    it "is a subclass of SSE::Stream" do
+      stream = A2A::SSE::JsonRpcStream.new(json_rpc_id: 1)
+      stream.is_a?(A2A::SSE::Stream).should == true
+      stream.is_a?(Protocol::HTTP::Body::Readable).should == true
+    end
+  end
+end

data/lib/a2a/sse/rest_stream.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "stream"
+
+module A2A
+  module SSE
+    # SSE stream for the HTTP+JSON/REST binding.
+    #
+    # Per the A2A spec, REST streaming returns SSE where each `data:` line
+    # is a bare StreamResponse JSON object (no envelope wrapping).
+    #
+    # This is essentially just an alias for Stream — the base class already
+    # emits bare JSON. We keep this as a named class for symmetry with
+    # JsonRpcStream and to make binding code self-documenting.
+    #
+    # Usage:
+    #
+    #   stream = A2A::SSE::RestStream.new
+    #
+    #   Async do
+    #     stream.event({ "task" => { ... } })
+    #     stream.finish
+    #   end
+    #
+    #   [200, A2A::SSE::Stream.headers, stream]
+    #
+    class RestStream < Stream
+    end
+  end
+end
+
+test do
+  describe "A2A::SSE::RestStream" do
+    it "emits bare JSON events (no envelope)" do
+      stream = A2A::SSE::RestStream.new
+
+      stream.event({ "statusUpdate" => { "taskId" => "t1" } })
+      stream.finish
+
+      chunk = stream.read
+      chunk.should.include('"statusUpdate"')
+      chunk.should.not.include('"jsonrpc"')
+    end
+
+    it "is a subclass of SSE::Stream" do
+      stream = A2A::SSE::RestStream.new
+      stream.is_a?(A2A::SSE::Stream).should == true
+    end
+  end
+end

data/lib/a2a/sse/stream.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "protocol/http/body/writable"
+require "json"
+
+module A2A
+  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::SSE::Stream.new
+    #
+    #   Async do
+    #     stream.event({ "task" => { ... } })
+    #     stream.event({ "statusUpdate" => { ... } })
+    #     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
+
+      # 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.
+      def self.headers
+        SSE_HEADERS
+      end
+    end
+  end
+end
+
+test do
+  require "async"
+
+  describe "A2A::SSE::Stream" do
+    it "formats SSE events correctly" do
+      stream = A2A::SSE::Stream.new
+
+      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::SSE::Stream.new
+
+      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::SSE::Stream.new
+
+      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::SSE::Stream.new
+      stream.is_a?(Protocol::HTTP::Body::Readable).should == true
+    end
+
+    it "provides standard SSE headers" do
+      headers = A2A::SSE::Stream.headers
+      headers["content-type"].should == "text/event-stream"
+      headers["cache-control"].should.include("no-cache")
+    end
+  end
+end

data/lib/a2a/sse.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "sse/stream"
+require_relative "sse/json_rpc_stream"
+require_relative "sse/rest_stream"

data/lib/a2a/store/processor.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "async"
+require "console"
+
+module A2A
+  module Store
+    # Async background task processor, modeled after async-job's Inline processor.
+    #
+    # The gospel (async-job) teaches:
+    #   - Async::Idler schedules tasks when the event loop is idle (backpressure)
+    #   - Each job runs in its own fiber (not thread)
+    #   - The returned Async::Task can be .wait'd for completion notification
+    #   - Errors are caught and logged, not re-raised
+    #   - task.defer_stop protects critical sections from interruption
+    #
+    # This processor enables A2A's non-blocking mode (return_immediately: true).
+    # The handler can enqueue work that executes after the HTTP response is sent.
+    #
+    # Usage:
+    #
+    #   processor = A2A::Store::Processor.new
+    #
+    #   # Fire and forget:
+    #   processor.call { store.update_state(task_id, "WORKING"); do_work; store.complete(task_id, result) }
+    #
+    #   # Wait for completion:
+    #   task = processor.call { do_work }
+    #   task.wait
+    #
+    class Processor
+      attr_reader :call_count, :complete_count, :failed_count
+
+      def initialize(parent: nil)
+        @parent         = parent
+        @call_count     = 0
+        @complete_count = 0
+        @failed_count   = 0
+      end
+
+      # Execute a block asynchronously in a background fiber.
+      #
+      # Returns the Async::Task so callers can optionally .wait on it.
+      #
+      # @yield the work to perform
+      # @return [Async::Task]
+      #
+      def call(&block)
+        @call_count += 1
+
+        parent.async do |task|
+          task.defer_stop do
+            yield
+          end
+          @complete_count += 1
+        rescue => error
+          @failed_count += 1
+          Console.error(self) { "Background task failed: #{error.message}" }
+        ensure
+          @call_count -= 1
+        end
+      end
+
+      def start
+        # Ensure we have an async context available
+      end
+
+      def stop
+        # Allow in-flight tasks to drain naturally
+      end
+
+      def status
+        {
+          in_flight: @call_count,
+          completed: @complete_count,
+          failed:    @failed_count,
+        }
+      end
+
+      private
+
+        def parent
+          @parent || Async::Task.current
+        end
+    end
+  end
+end
+
+test do
+  require "async"
+
+  describe "A2A::Store::Processor" do
+    it "executes blocks asynchronously" do
+      executed = false
+
+      Sync do
+        processor = A2A::Store::Processor.new
+        task = processor.call { executed = true }
+        task.wait
+      end
+
+      executed.should == true
+    end
+
+    it "tracks call counts" do
+      Sync do
+        processor = A2A::Store::Processor.new
+        task = processor.call { "work" }
+        task.wait
+
+        processor.complete_count.should == 1
+        processor.call_count.should == 0  # decremented after completion
+      end
+    end
+
+    it "handles errors gracefully" do
+      Sync do
+        processor = A2A::Store::Processor.new
+        task = processor.call { raise "boom" }
+        task.wait rescue nil  # task may re-raise
+
+        processor.failed_count.should == 1
+      end
+    end
+
+    it "returns status" do
+      Sync do
+        processor = A2A::Store::Processor.new
+        status = processor.status
+        status[:in_flight].should == 0
+        status[:completed].should == 0
+        status[:failed].should == 0
+      end
+    end
+  end
+end