agent2agent 1.1.0 → 2.0.0

data/lib/a2a/schema/validation_error.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "a2a"
-
-module A2A
-  module Schema
-    # Raised when a Definition instance fails schema validation.
-    #
-    # Collects JSONSchemer error details and formats them as a
-    # human-readable list with dot-notation field paths.
-    #
-    #   Agent Card validation failed:
-    #     - name is required but missing
-    #     - capabilities.streaming must be boolean, got string
-    #
-    class ValidationError < StandardError
-      attr_reader :errors, :definition_name, :data
-
-      def initialize(errors, definition_name:, data: nil)
-        @errors          = errors
-        @definition_name = definition_name
-        @data            = data
-
-        super(build_message)
-      end
-
-      private
-
-        def build_message
-          lines = errors.map { |e| "  - #{format_error(e)}" }
-          "#{definition_name} validation failed:\n#{lines.join("\n")}"
-        end
-
-        def format_error(error)
-          path  = format_path(error)
-          type  = error["type"]
-
-          case type
-          when "required"
-            missing = error.dig("details", "missing_keys")&.join(", ") || "unknown"
-            if path.empty?
-              "#{missing} is required but missing"
-            else
-              "#{path}.#{missing} is required but missing"
-            end
-          when "type"
-            expected = Array(error.dig("schema", "type")).join(" or ")
-            "#{path.empty? ? "(root)" : path} must be #{expected}"
-          when "enum"
-            allowed = error.dig("schema", "enum")&.join(", ") || "?"
-            "#{path.empty? ? "(root)" : path} must be one of: #{allowed}"
-          when "pattern"
-            pattern = error.dig("schema", "pattern")
-            "#{path.empty? ? "(root)" : path} must match pattern #{pattern}"
-          when "format"
-            fmt = error.dig("schema", "format")
-            "#{path.empty? ? "(root)" : path} must be a valid #{fmt}"
-          when "minimum", "maximum"
-            "#{path.empty? ? "(root)" : path} #{error["error"]}"
-          when "additionalProperties"
-            "#{path.empty? ? "(root)" : path} has unknown properties"
-          else
-            detail = error["error"] || error["type"] || "invalid"
-            "#{path.empty? ? "(root)" : path} #{detail}"
-          end
-        end
-
-        # Convert JSON pointer like "/properties/capabilities/streaming"
-        # to dot notation like "capabilities.streaming"
-        def format_path(error)
-          pointer = error["data_pointer"].to_s
-          return "" if pointer.empty? || pointer == "/"
-
-          pointer.delete_prefix("/").gsub("/", ".")
-        end
-    end
-  end
-end
-
-test do
-  error_data = [
-    {
-      "data_pointer" => "",
-      "type" => "required",
-      "details" => { "missing_keys" => ["name"] },
-      "schema" => {},
-      "error" => "missing keys: name"
-    }
-  ]
-
-  err = A2A::Schema::ValidationError.new(error_data, definition_name: "Agent Card")
-
-  it "includes the definition name" do
-    err.message.should.include?("Agent Card")
-  end
-
-  it "formats required errors" do
-    err.message.should.include?("name is required but missing")
-  end
-
-  it "stores the errors array" do
-    err.errors.should == error_data
-  end
-
-  it "stores the definition name" do
-    err.definition_name.should == "Agent Card"
-  end
-
-  nested = A2A::Schema::ValidationError.new(
-    [{ "data_pointer" => "/capabilities/streaming", "type" => "type",
-       "schema" => { "type" => "boolean" }, "error" => "wrong type" }],
-    definition_name: "Agent Card"
-  )
-
-  it "formats nested paths with dot notation" do
-    nested.message.should.include?("capabilities.streaming must be boolean")
-  end
-
-  additional = A2A::Schema::ValidationError.new(
-    [{ "data_pointer" => "/foo", "type" => "additionalProperties",
-       "schema" => {}, "error" => "unexpected" }],
-    definition_name: "Test"
-  )
-
-  it "formats additionalProperties errors" do
-    additional.message.should.include?("foo has unknown properties")
-  end
-end

data/lib/a2a/server/dispatcher.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "console"
-require "a2a"
-
-module A2A
-  class Server
-    # Routes incoming A2A operations to their registered handler stacks.
-    #
-    # Each operation maps to exactly one Rack app (a compiled middleware
-    # stack built by the Agent DSL). The Dispatcher is a terminal Rack app
-    # that reads env["a2a.operation"] set by Triage, looks up the matching
-    # route, and calls it.
-    #
-    # Returns domain objects (A2A::Schema::Definition or A2A::Error) —
-    # the binding layer is responsible for formatting these into HTTP.
-    #
-    class Dispatcher
-      def initialize
-        @routes = {}
-      end
-
-      # Register a handler object.
-      #
-      # The handler must respond to:
-      #   #operations -> Array(String)  (e.g. ["SendMessage", "GetTask"])
-      #   #call(env)  -> A2A::Schema::Definition | A2A::Error
-      #
-      def register(handler)
-        handler.operations.each do |op|
-          @routes[op] = handler
-          Console.info(self) { "Registered #{handler.class.name} for #{op}" }
-        end
-      end
-
-      def call(env)
-        operation = env["a2a.operation"]
-        app = @routes[operation]
-
-        unless app
-          raise A2A::UnsupportedOperationError.new(
-            message: "Operation not supported: #{operation}"
-          )
-        end
-
-        app.call(env)
-      rescue A2A::Error => e
-        e
-      rescue => e
-        Console.error(self, "Handler raised #{e.class}: #{e.message}", e)
-        A2A::Error.new("Internal error", code: -32603, http_status: 500)
-      end
-
-      def handler_count
-        @routes.size
-      end
-    end
-  end
-end
-
-test do
-  describe "A2A::Server::Dispatcher" do
-    it "registers and dispatches to a handler" do
-      handler = Object.new
-      handler.define_singleton_method(:operations) { ["SendMessage"] }
-      handler.define_singleton_method(:call) { |env| :dispatched }
-
-      dispatcher = A2A::Server::Dispatcher.new
-      dispatcher.register(handler)
-      dispatcher.handler_count.should == 1
-
-      env = { "a2a.operation" => "SendMessage" }
-      result = dispatcher.call(env)
-      result.should == :dispatched
-    end
-
-    it "returns UnsupportedOperationError for unknown operations" do
-      dispatcher = A2A::Server::Dispatcher.new
-      env = { "a2a.operation" => "UnknownOp" }
-      result = dispatcher.call(env)
-      result.should.be.is_a(A2A::UnsupportedOperationError)
-      result.code.should == -32004
-    end
-
-    it "returns A2A::Error when handler raises one" do
-      handler = Object.new
-      handler.define_singleton_method(:operations) { ["SendMessage"] }
-      handler.define_singleton_method(:call) { |_| raise A2A::TaskNotFoundError.new("t-1") }
-
-      dispatcher = A2A::Server::Dispatcher.new
-      dispatcher.register(handler)
-
-      result = dispatcher.call({ "a2a.operation" => "SendMessage" })
-      result.should.be.is_a(A2A::TaskNotFoundError)
-      result.code.should == -32001
-    end
-
-    it "returns internal error when handler raises unexpected exception" do
-      handler = Object.new
-      handler.define_singleton_method(:operations) { ["SendMessage"] }
-      handler.define_singleton_method(:call) { |_| raise "boom" }
-
-      dispatcher = A2A::Server::Dispatcher.new
-      dispatcher.register(handler)
-
-      result = dispatcher.call({ "a2a.operation" => "SendMessage" })
-      result.should.be.is_a(A2A::Error)
-      result.code.should == -32603
-      result.http_status.should == 500
-    end
-
-    it "dispatches to multiple operations from one handler" do
-      received = []
-      handler = Object.new
-      handler.define_singleton_method(:operations) { ["SendMessage", "GetTask"] }
-      handler.define_singleton_method(:call) { |env| received << env["a2a.operation"]; :ok }
-
-      dispatcher = A2A::Server::Dispatcher.new
-      dispatcher.register(handler)
-
-      dispatcher.call({ "a2a.operation" => "SendMessage" })
-      dispatcher.call({ "a2a.operation" => "GetTask" })
-      received.should == ["SendMessage", "GetTask"]
-    end
-  end
-end

data/lib/a2a/sse/json_rpc_stream.rb

@@ -1,88 +0,0 @@
-# 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(
-    #     task_id: "t1", context_id: "c1", json_rpc_id: 1
-    #   )
-    #
-    #   Async do
-    #     stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "..." })
-    #     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(
-        task_id: "t1", context_id: "c1", json_rpc_id: 42
-      )
-
-      stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "2025-01-01T00:00:00Z" })
-      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(
-        task_id: "t1", context_id: "c1", json_rpc_id: 1
-      )
-      stream.is_a?(A2A::SSE::Stream).should == true
-      stream.is_a?(Protocol::HTTP::Body::Readable).should == true
-    end
-
-    it "typed methods chain through JSON-RPC envelope" do
-      stream = A2A::SSE::JsonRpcStream.new(
-        task_id: "t1", context_id: "c1", json_rpc_id: 7
-      )
-
-      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["jsonrpc"].should == "2.0"
-      parsed["id"].should == 7
-      parsed["result"]["statusUpdate"]["taskId"].should == "t1"
-      parsed["result"]["statusUpdate"]["contextId"].should == "c1"
-    end
-  end
-end

data/lib/a2a/sse/rest_stream.rb

@@ -1,62 +0,0 @@
-# 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(task_id: "t1", context_id: "c1")
-    #
-    #   Async do
-    #     stream.task(status: { state: "TASK_STATE_WORKING", timestamp: "..." })
-    #     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(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
-      chunk.should.include('"statusUpdate"')
-      chunk.should.not.include('"jsonrpc"')
-    end
-
-    it "is a subclass of SSE::Stream" do
-      stream = A2A::SSE::RestStream.new(task_id: "t1", context_id: "c1")
-      stream.is_a?(A2A::SSE::Stream).should == true
-    end
-
-    it "injects task_id and context_id into typed events" do
-      stream = A2A::SSE::RestStream.new(task_id: "t1", context_id: "c1")
-
-      stream.task(status: { state: "TASK_STATE_WORKING" })
-      stream.finish
-
-      chunk = stream.read
-      parsed = JSON.parse(chunk.sub(/\Adata: /, "").strip)
-      parsed["task"]["id"].should == "t1"
-      parsed["task"]["contextId"].should == "c1"
-    end
-  end
-end

data/lib/a2a/sse/stream.rb

@@ -1,257 +0,0 @@
-# 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::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.
-      def self.headers
-        SSE_HEADERS
-      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::Schema["Stream Response"]
-
-      stream_response.property_refs.each do |camel_key, (_kind, title)|
-        target_props = A2A::Schema[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::Schema[title].new(merged).to_h })
-        end
-      end
-    end
-  end
-end
-
-test do
-  require "async"
-
-  describe "A2A::SSE::Stream" do
-    it "formats SSE events correctly" do
-      stream = A2A::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::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::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::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::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::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::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::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::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::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::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
-end

data/lib/traces/provider/a2a/server/dispatcher.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../../../a2a/server/dispatcher"
-require "traces/provider"
-
-Traces::Provider(A2A::Server::Dispatcher) do
-  def call(env)
-    attributes = {
-      "a2a.operation" => env["a2a.operation"],
-    }
-
-    Traces.trace("a2a.server.dispatcher.call", attributes: attributes) do |span|
-      super.tap do |status, headers, body|
-        span["http.status_code"] = status
-
-        if env["a2a.stream"]
-          span["a2a.response_type"] = "stream"
-        elsif env["a2a.error"]
-          span["a2a.response_type"] = "error"
-        elsif env["a2a.result"]
-          span["a2a.response_type"] = "result"
-        end
-      end
-    end
-  end
-end