simple_a2a 0.1.0

data/lib/simple_a2a/models/push_notification_config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class PushNotificationConfig < Base
+      attribute :id
+      attribute :task_id
+      attribute :webhook_url,         required: true
+      attribute :authentication_info, type: AuthenticationInfo
+      attribute :event_types,         default: -> { [] }
+
+      def valid?
+        !webhook_url.nil? && !webhook_url.empty?
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/security_scheme.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class SecurityScheme < Base
+      attribute :type,             required: true
+      attribute :description
+      attribute :scheme
+      attribute :bearer_format
+      attribute :flows
+      attribute :open_id_connect_url
+      attribute :in
+      attribute :name
+    end
+  end
+end

data/lib/simple_a2a/models/send_message_configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class SendMessageConfiguration < Base
+      attribute :accepted_output_modes,          default: -> { [] }
+      attribute :task_push_notification_config
+      attribute :history_length
+      attribute :return_immediately,             default: false
+    end
+  end
+end

data/lib/simple_a2a/models/stream_response.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class StreamResponse < Base
+      attribute :task
+      attribute :message
+      attribute :status_update
+      attribute :artifact_update
+
+      def task?            = !task.nil?
+      def message?         = !message.nil?
+      def status_update?   = !status_update.nil?
+      def artifact_update? = !artifact_update.nil?
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+        if hash["task"]
+          new(task: Task.from_hash(hash["task"]))
+        elsif hash["message"]
+          new(message: Message.from_hash(hash["message"]))
+        elsif hash["statusUpdate"]
+          new(status_update: hash["statusUpdate"])
+        elsif hash["artifactUpdate"]
+          new(artifact_update: hash["artifactUpdate"])
+        else
+          new
+        end
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/task.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class Task < Base
+      attribute :id
+      attribute :context_id
+      attribute :status,    type: TaskStatus, required: true
+      attribute :artifacts, type: [Artifact], default: -> { [] }
+      attribute :history,   type: [Message],  default: -> { [] }
+      attribute :metadata
+
+      def initialize(**kwargs)
+        kwargs[:id]         ||= SecureRandom.uuid
+        kwargs[:context_id] ||= SecureRandom.uuid
+        super
+      end
+
+      def state        = status&.state
+      def terminal?    = status&.terminal?   || false
+      def interrupted? = status&.interrupted? || false
+
+      def start!
+        transition!(Types::TaskState::WORKING)
+      end
+
+      def complete!(artifacts: [])
+        self.artifacts = artifacts unless artifacts.empty?
+        transition!(Types::TaskState::COMPLETED)
+      end
+
+      def fail!(message: nil)
+        transition!(Types::TaskState::FAILED, message: message)
+      end
+
+      def cancel!
+        transition!(Types::TaskState::CANCELED)
+      end
+
+      def reject!(message: nil)
+        transition!(Types::TaskState::REJECTED, message: message)
+      end
+
+      def require_input!(message: nil)
+        transition!(Types::TaskState::INPUT_REQUIRED, message: message)
+      end
+
+      def require_auth!(message: nil)
+        transition!(Types::TaskState::AUTH_REQUIRED, message: message)
+      end
+
+      def transition!(new_state, message: nil)
+        self.status = TaskStatus.new(state: new_state, message: message)
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/task_artifact_update_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class TaskArtifactUpdateEvent < Base
+      attribute :task_id,    required: true
+      attribute :context_id, required: true
+      attribute :artifact,   type: Artifact, required: true
+      attribute :append,     default: false
+      attribute :last_chunk, default: false
+      attribute :metadata
+
+      def append?     = !!append
+      def last_chunk? = !!last_chunk
+
+      def to_h
+        super.merge("type" => "TaskArtifactUpdateEvent")
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/task_status.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class TaskStatus < Base
+      attribute :state,     required: true
+      attribute :message,   type: Message
+      attribute :timestamp
+
+      def initialize(**kwargs)
+        kwargs[:timestamp] ||= Time.now.iso8601
+        super
+      end
+
+      def terminal?    = Types::TaskState.terminal?(state)
+      def interrupted? = Types::TaskState.interrupted?(state)
+      def active?      = Types::TaskState.active?(state)
+    end
+  end
+end

data/lib/simple_a2a/models/task_status_update_event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    class TaskStatusUpdateEvent < Base
+      attribute :task_id,    required: true
+      attribute :context_id, required: true
+      attribute :status,     type: TaskStatus, required: true
+      attribute :final,      default: false
+      attribute :metadata
+
+      def final? = !!final
+
+      def to_h
+        super.merge("type" => "TaskStatusUpdateEvent")
+      end
+    end
+  end
+end

data/lib/simple_a2a/models/types.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module A2A
+  module Models
+    module Types
+      module TaskState
+        SUBMITTED      = "submitted"
+        WORKING        = "working"
+        COMPLETED      = "completed"
+        FAILED         = "failed"
+        CANCELED       = "canceled"
+        REJECTED       = "rejected"
+        INPUT_REQUIRED = "input_required"
+        AUTH_REQUIRED  = "auth_required"
+
+        TERMINAL    = [COMPLETED, FAILED, CANCELED, REJECTED].freeze
+        INTERRUPTED = [INPUT_REQUIRED, AUTH_REQUIRED].freeze
+        ACTIVE      = [SUBMITTED, WORKING].freeze
+        ALL         = (TERMINAL + INTERRUPTED + ACTIVE).freeze
+
+        def self.terminal?(state)    = TERMINAL.include?(state)
+        def self.interrupted?(state) = INTERRUPTED.include?(state)
+        def self.active?(state)      = ACTIVE.include?(state)
+      end
+
+      module Role
+        USER  = "user"
+        AGENT = "agent"
+        ALL   = [USER, AGENT].freeze
+      end
+
+      module BindingType
+        JSON_RPC = "json-rpc"
+        HTTP     = "http"
+        GRPC     = "grpc"
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/agent_executor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module A2A
+  module Server
+    class AgentExecutor
+      def call(context)
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+
+      def cancel(context)
+        context.task.cancel!
+        context.emit_status(final: true)
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/app.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "roda"
+require "protocol/http/body/writable"
+
+module A2A
+  module Server
+    class App < Roda
+      SUPPORTED_VERSIONS = %w[1.0 0.3].freeze
+
+      plugin :json
+      plugin :json_parser
+      plugin :halt
+      plugin :all_verbs
+
+      def self.configure(agent_card:, storage:, executor:, event_router:, push_sender: nil)
+        @agent_card   = agent_card
+        @storage      = storage
+        @executor     = executor
+        @event_router = event_router
+        @push_sender  = push_sender
+      end
+
+      class << self
+        attr_reader :agent_card, :storage, :executor, :event_router, :push_sender
+      end
+
+      route do |r|
+        # A2A version negotiation
+        a2a_version = request.env["HTTP_A2A_VERSION"]
+        if a2a_version && !SUPPORTED_VERSIONS.include?(a2a_version)
+          err = JsonRpc::Response.error(
+            id: nil,
+            code: JsonRpc::ErrorCode::VERSION_NOT_SUPPORTED,
+            message: "Unsupported A2A version: #{a2a_version}"
+          )
+          r.halt([200, { "Content-Type" => "application/json" }, [err]])
+        end
+
+        r.get "agentCard" do
+          self.class.agent_card.to_h
+        end
+
+        r.post do
+          body = request.body.read
+          rpc_req = begin
+            JsonRpc::Request.parse(body)
+          rescue JsonRpc::ParseError => e
+            err = JsonRpc::Response.error(id: nil, code: JsonRpc::ErrorCode::PARSE_ERROR, message: e.message)
+            r.halt([200, { "Content-Type" => "application/json" }, [err]])
+          rescue JsonRpc::InvalidRequestError => e
+            err = JsonRpc::Response.error(id: nil, code: JsonRpc::ErrorCode::INVALID_REQUEST, message: e.message)
+            r.halt([200, { "Content-Type" => "application/json" }, [err]])
+          end
+
+          # SSE has different headers and body — intercept before normal dispatch.
+          # The body is an Enumerator so Falcon streams each event to the client
+          # as the executor yields it, rather than buffering the whole response.
+          if rpc_req.method == "tasks/sendSubscribe"
+            r.halt([200, {
+              "Content-Type"      => "text/event-stream",
+              "Cache-Control"     => "no-cache",
+              "X-Accel-Buffering" => "no"
+            }, handle_send_subscribe(rpc_req)])
+          end
+
+          result = dispatch(rpc_req)
+          response["Content-Type"] = "application/json"
+          result
+        end
+      end
+
+      private
+
+      def dispatch(rpc_req)
+        case rpc_req.method
+        when "tasks/send"                    then handle_send(rpc_req)
+        when "tasks/get"                     then handle_get(rpc_req)
+        when "tasks/list"                    then handle_list(rpc_req)
+        when "tasks/cancel"                  then handle_cancel(rpc_req)
+        when "tasks/pushNotification/set"    then handle_push_set(rpc_req)
+        when "tasks/pushNotification/get"    then handle_push_get(rpc_req)
+        when "tasks/pushNotification/delete" then handle_push_delete(rpc_req)
+        when "tasks/pushNotification/list"   then handle_push_list(rpc_req)
+        else
+          JsonRpc::Response.error(
+            id:      rpc_req.id,
+            code:    JsonRpc::ErrorCode::METHOD_NOT_FOUND,
+            message: "Method not found: #{rpc_req.method}"
+          )
+        end
+      rescue A2A::Error => e
+        JsonRpc::Response.from_error(id: rpc_req.id, error: e)
+      rescue StandardError => e
+        JsonRpc::Response.from_error(id: rpc_req.id, error: e)
+      end
+
+      def handle_send(rpc_req)
+        params   = rpc_req.params || {}
+        msg_hash = params["message"]
+        raise JsonRpc::InvalidParamsError, "message is required" unless msg_hash.is_a?(Hash)
+        message  = Models::Message.from_hash(msg_hash)
+
+        task = Models::Task.new(
+          status: Models::TaskStatus.new(state: Models::Types::TaskState::SUBMITTED)
+        )
+        self.class.storage.save(task)
+
+        ctx = Server::Context.new(
+          task:         task,
+          message:      message,
+          storage:      self.class.storage,
+          event_router: self.class.event_router
+        )
+        self.class.executor.call(ctx)
+        self.class.storage.save(task)
+
+        JsonRpc::Response.success(id: rpc_req.id, result: task.to_h)
+      end
+
+      def handle_get(rpc_req)
+        params  = rpc_req.params || {}
+        task_id = params["id"] || params["taskId"]
+        raise JsonRpc::InvalidParamsError, "id is required" unless task_id
+
+        task = self.class.storage.find!(task_id)
+        JsonRpc::Response.success(id: rpc_req.id, result: task.to_h)
+      end
+
+      def handle_list(rpc_req)
+        tasks = self.class.storage.list
+        JsonRpc::Response.success(id: rpc_req.id, result: tasks.map(&:to_h))
+      end
+
+      def handle_cancel(rpc_req)
+        params  = rpc_req.params || {}
+        task_id = params["id"] || params["taskId"]
+        raise JsonRpc::InvalidParamsError, "id is required" unless task_id
+
+        task = self.class.storage.find!(task_id)
+        raise TaskNotCancelableError, "Task #{task_id} is already terminal" if task.terminal?
+
+        ctx = Server::Context.new(
+          task:         task,
+          message:      nil,
+          storage:      self.class.storage,
+          event_router: self.class.event_router
+        )
+        self.class.executor.cancel(ctx)
+        self.class.storage.save(task)
+
+        JsonRpc::Response.success(id: rpc_req.id, result: task.to_h)
+      end
+
+      def handle_send_subscribe(rpc_req)
+        params   = rpc_req.params || {}
+        msg_hash = params["message"]
+        raise JsonRpc::InvalidParamsError, "message is required" unless msg_hash.is_a?(Hash)
+        message  = Models::Message.from_hash(msg_hash)
+
+        task = Models::Task.new(
+          status: Models::TaskStatus.new(state: Models::Types::TaskState::SUBMITTED)
+        )
+        self.class.storage.save(task)
+
+        storage  = self.class.storage
+        executor = self.class.executor
+
+        # Protocol::HTTP::Body::Writable is a Readable subclass.
+        # Protocol::Rack detects this and does NOT wrap it in an Enumerable
+        # fiber — Falcon reads it directly via queue.dequeue in its async task.
+        # The executor runs in a sibling async task and pushes events via
+        # output.write (queue.enqueue), which is fully async-safe.
+        # This avoids the FiberError that Enumerator::Yielder#<< raises when
+        # called from inside an LLM streaming callback (an async task context
+        # where the Enumerator consumer fiber is not currently waiting).
+        output = Protocol::HTTP::Body::Writable.new
+
+        Async::Task.current.async do
+          streaming_router = Object.new.tap do |ro|
+            ro.define_singleton_method(:publish)   { |_, ev| output.write("data: #{JSON.generate({ 'jsonrpc' => '2.0', 'result' => ev.to_h })}\n\n") }
+            ro.define_singleton_method(:open)      { |*| }
+            ro.define_singleton_method(:close)     { |*| }
+            ro.define_singleton_method(:channel?)  { |*| false }
+            ro.define_singleton_method(:subscribe) { |*| }
+          end
+
+          ctx = Server::Context.new(
+            task:         task,
+            message:      message,
+            storage:      storage,
+            event_router: streaming_router
+          )
+
+          executor.call(ctx)
+          storage.save(task)
+        rescue => e
+          output.write("data: #{JSON.generate({ 'jsonrpc' => '2.0', 'error' => { 'code' => -32000, 'message' => e.message } })}\n\n") rescue nil
+        ensure
+          output.close_write rescue nil
+        end
+
+        output
+      end
+
+      def handle_push_set(rpc_req)
+        raise PushNotificationNotSupportedError unless self.class.agent_card&.capabilities&.push_notifications
+        JsonRpc::Response.success(id: rpc_req.id, result: true)
+      end
+
+      def handle_push_get(rpc_req)
+        raise PushNotificationNotSupportedError unless self.class.agent_card&.capabilities&.push_notifications
+        JsonRpc::Response.success(id: rpc_req.id, result: nil)
+      end
+
+      def handle_push_delete(rpc_req)
+        raise PushNotificationNotSupportedError unless self.class.agent_card&.capabilities&.push_notifications
+        JsonRpc::Response.success(id: rpc_req.id, result: true)
+      end
+
+      def handle_push_list(rpc_req)
+        raise PushNotificationNotSupportedError unless self.class.agent_card&.capabilities&.push_notifications
+        JsonRpc::Response.success(id: rpc_req.id, result: [])
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module A2A
+  module Server
+    class Base
+      attr_reader :agent_card, :executor, :storage, :event_router, :push_sender
+
+      def initialize(
+        agent_card:,
+        executor:,
+        storage:      Storage::Memory.new,
+        push_sender:  nil,
+        host:         "localhost",
+        port:         9292
+      )
+        @agent_card   = agent_card
+        @executor     = executor
+        @storage      = storage
+        @event_router = EventRouter.new
+        @push_sender  = push_sender
+        @host         = host
+        @port         = port
+      end
+
+      def rack_app
+        klass = Class.new(App)
+        klass.configure(
+          agent_card:   @agent_card,
+          storage:      @storage,
+          executor:     @executor,
+          event_router: @event_router,
+          push_sender:  @push_sender
+        )
+        klass.freeze.app
+      end
+
+      def run
+        app = rack_app
+        FalconRunner.new(app, host: @host, port: @port).run
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module A2A
+  module Server
+    class Context
+      attr_reader :task, :message, :storage, :event_router, :config
+
+      def initialize(task:, message:, storage:, event_router:, config: nil)
+        @task         = task
+        @message      = message
+        @storage      = storage
+        @event_router = event_router
+        @config       = config || {}
+      end
+
+      def save_task
+        storage.save(task)
+      end
+
+      def emit_status(final: false)
+        event = Models::TaskStatusUpdateEvent.new(
+          task_id:    task.id,
+          context_id: task.context_id,
+          status:     task.status,
+          final:      final
+        )
+        storage.save(task)
+        event_router.publish(task.id, event)
+      end
+
+      def emit_artifact(artifact, append: false, last_chunk: false)
+        event = Models::TaskArtifactUpdateEvent.new(
+          task_id:    task.id,
+          context_id: task.context_id,
+          artifact:   artifact,
+          append:     append,
+          last_chunk: last_chunk
+        )
+        event_router.publish(task.id, event)
+      end
+    end
+
+  end
+end

data/lib/simple_a2a/server/event_router.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "typed_bus"
+
+module A2A
+  module Server
+    class EventRouter
+      def initialize
+        @bus = TypedBus::MessageBus.new
+      end
+
+      def open(task_id)
+        return if @bus.channel?(task_id.to_sym)
+        @bus.add_channel(task_id.to_sym, type: nil, timeout: nil)
+      end
+
+      def close(task_id)
+        @bus.remove_channel(task_id.to_sym)
+      end
+
+      def publish(task_id, event)
+        sym = task_id.to_sym
+        open(task_id) unless @bus.channel?(sym)
+        @bus.publish(sym, event)
+      rescue ArgumentError
+        nil
+      end
+
+      def subscribe(task_id, &block)
+        sym = task_id.to_sym
+        open(task_id) unless @bus.channel?(sym)
+        @bus.subscribe(sym) do |delivery|
+          block.call(delivery.message)
+          delivery.ack!
+        end
+      end
+
+      def unsubscribe(task_id, id_or_block)
+        return unless @bus.channel?(task_id.to_sym)
+        @bus.unsubscribe(task_id.to_sym, id_or_block)
+      rescue ArgumentError
+        nil
+      end
+
+      def channel?(task_id)
+        @bus.channel?(task_id.to_sym)
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/falcon_runner.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "falcon"
+require "async"
+require "async/http/endpoint"
+
+module A2A
+  module Server
+    class FalconRunner
+      DEFAULT_HOST = "localhost"
+      DEFAULT_PORT = 9292
+
+      def initialize(app, host: DEFAULT_HOST, port: DEFAULT_PORT)
+        @app  = app
+        @host = host
+        @port = port
+      end
+
+      def run
+        endpoint = Async::HTTP::Endpoint.parse("http://#{@host}:#{@port}")
+        server   = Falcon::Server.new(Falcon::Server.middleware(@app), endpoint)
+
+        Async do
+          server.run
+        end
+      rescue Interrupt
+        # Ctrl-C — clean shutdown, no backtrace needed
+      end
+    end
+  end
+end