acp_sdk_async 0.2.0

data/lib/acp/connection.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+require "async/queue"
+require_relative "exceptions"
+require_relative "schema_base"
+require_relative "transport"
+require_relative "wait"
+
+module ACP
+  StreamEvent = Struct.new(:direction, :message, keyword_init: true) do
+    def incoming? = direction == :incoming
+    def outgoing? = direction == :outgoing
+  end
+
+  class Connection
+    attr_reader :transport
+
+    def initialize(handler, transport, worker_grace: 0.5)
+      @handler = handler
+      @transport = transport
+      @worker_grace = worker_grace
+      @next_id = 0
+      @pending = {}
+      @closed = false
+      @mutex = Mutex.new
+      @workers = Set.new
+      @observers = []
+      @listen_worker = nil
+      @notification_queue = ::Async::Queue.new
+      @notification_worker = nil
+      @finished = Wait::Latch.new
+    end
+
+    def closed?
+      @closed
+    end
+
+    def add_observer(callable = nil, &block)
+      observer = callable || block
+      raise ArgumentError, "Observer must respond to #call" unless observer.respond_to?(:call)
+
+      @mutex.synchronize { @observers << observer }
+      observer
+    end
+
+    def remove_observer(observer)
+      @mutex.synchronize { @observers.delete(observer) }
+    end
+
+    def listen
+      start_notification_worker
+      receive_loop
+    rescue StandardError => e
+      ACP.logger.error("acp: receive loop failed: #{e.class}: #{e.message}")
+      raise
+    ensure
+      reject_all(ConnectionError.new("Connection closed"))
+      stop_notification_worker
+      @finished.open
+    end
+
+    def start
+      return @listen_worker if listening?
+
+      Wait.ensure_reactor!
+      @finished = Wait::Latch.new
+      @listen_worker = Wait.spawn("acp-listen") { listen }
+    end
+
+    def join(timeout = nil)
+      @finished.wait(timeout)
+    end
+
+    def send_request(method, params = nil, timeout: nil)
+      raise ConnectionError, "Connection closed" if @closed
+
+      request_id = next_id
+      promise = Wait::Promise.new
+      @mutex.synchronize { @pending[request_id] = promise }
+
+      payload = { "jsonrpc" => "2.0", "id" => request_id, "method" => method }
+      payload["params"] = serialize(params) unless params.nil?
+
+      begin
+        write(payload)
+      rescue StandardError
+        @mutex.synchronize { @pending.delete(request_id) }
+        raise
+      end
+
+      begin
+        promise.wait(timeout)
+      rescue TimeoutError
+        @mutex.synchronize { @pending.delete(request_id) }
+        raise TimeoutError, "Request #{method} (id=#{request_id}) timed out after #{timeout}s"
+      end
+    end
+
+    def send_notification(method, params = nil)
+      raise ConnectionError, "Connection closed" if @closed
+
+      payload = { "jsonrpc" => "2.0", "method" => method }
+      payload["params"] = serialize(params) unless params.nil?
+      write(payload)
+    end
+
+    def drain_notifications(timeout: nil)
+      return true unless Wait.alive?(@notification_worker)
+
+      latch = Wait::Latch.new
+      @notification_queue.push(latch)
+      latch.wait(timeout)
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      reject_all(ConnectionError.new("Connection closed"))
+      begin
+        @transport.close
+      rescue StandardError => e
+        ACP.logger.debug("acp: transport close failed: #{e.message}")
+      end
+      stop_notification_worker
+      stop_workers
+    end
+
+    private
+
+    def next_id
+      @mutex.synchronize do
+        id = @next_id
+        @next_id += 1
+        id
+      end
+    end
+
+    def serialize(params)
+      Schema.serialize(params)
+    end
+
+    def write(payload)
+      notify_observers(:outgoing, payload)
+      @transport.send_message(payload)
+    end
+
+    def receive_loop
+      loop do
+        break if @closed
+
+        message = begin
+          @transport.receive_message
+        rescue TimeoutError => e
+          ACP.logger.error("acp: #{e.message}")
+          break
+        rescue ConnectionError => e
+          ACP.logger.debug("acp: receive failed: #{e.message}")
+          break
+        rescue ::Async::Cancel
+          break
+        end
+        break if message.nil?
+
+        notify_observers(:incoming, message)
+        process_message(message)
+      end
+    end
+
+    def process_message(message)
+      unless message.is_a?(Hash)
+        ACP.logger.warn("acp: ignoring non-object message: #{message.inspect[0, 200]}")
+        return
+      end
+
+      method = message["method"]
+      has_id = message.key?("id")
+
+      if method
+        unless method.is_a?(String)
+          respond_error(message["id"], RequestError.invalid_request("details" => "method must be a string")) if has_id
+          return
+        end
+
+        if has_id
+          spawn_worker("acp-request:#{method}") { run_request(message) }
+        else
+          @notification_queue.push(message)
+        end
+        return
+      end
+
+      if has_id
+        handle_response(message)
+      else
+        ACP.logger.warn("acp: ignoring message without method or id: #{message.inspect[0, 200]}")
+      end
+    end
+
+    def run_request(message)
+      payload = { "jsonrpc" => "2.0", "id" => message["id"] }
+      begin
+        result = @handler.call(message["method"], message["params"], false)
+        payload["result"] = serialize(result)
+      rescue RequestError => e
+        payload["error"] = e.to_error_obj
+      rescue Schema::ValidationError => e
+        payload["error"] = RequestError.invalid_params(
+          "errors" => [{ "message" => e.message, "loc" => e.path }]
+        ).to_error_obj
+      rescue ::Async::Cancel
+        return
+      rescue StandardError => e
+        ACP.logger.error("acp: handler for #{message['method']} failed: #{e.class}: #{e.message}")
+        payload["error"] = RequestError.internal_error("details" => e.message).to_error_obj
+      end
+      write(payload)
+    rescue ConnectionError => e
+      ACP.logger.debug("acp: could not send response for #{message['method']}: #{e.message}")
+    rescue ::Async::Cancel
+      nil
+    end
+
+    def respond_error(id, error)
+      write({ "jsonrpc" => "2.0", "id" => id, "error" => error.to_error_obj })
+    rescue ConnectionError, ::Async::Cancel
+      nil
+    end
+
+    def run_notification(message)
+      @handler.call(message["method"], message["params"], true)
+    rescue ::Async::Cancel
+      nil
+    rescue StandardError => e
+      ACP.logger.error("acp: notification handler for #{message['method']} failed: #{e.class}: #{e.message}")
+    end
+
+    def handle_response(message)
+      promise = @mutex.synchronize { @pending.delete(message["id"]) }
+      unless promise
+        ACP.logger.debug("acp: response for unknown request id #{message['id'].inspect}")
+        return
+      end
+
+      if message.key?("error")
+        error = message["error"] || {}
+        promise.reject(RequestError.new(error["code"] || -32603, error["message"] || "Error", error["data"]))
+      else
+        promise.resolve(message["result"])
+      end
+    end
+
+    def reject_all(error)
+      pending = @mutex.synchronize do
+        items = @pending.values
+        @pending.clear
+        items
+      end
+      pending.each { |promise| promise.reject(error) }
+    end
+
+    def notify_observers(direction, message)
+      observers = @mutex.synchronize { @observers.dup }
+      return if observers.empty?
+
+      event = StreamEvent.new(direction: direction, message: message)
+      observers.each do |observer|
+        observer.call(event)
+      rescue StandardError => e
+        ACP.logger.error("acp: observer failed: #{e.class}: #{e.message}")
+      end
+    end
+
+    def start_notification_worker
+      return if Wait.alive?(@notification_worker)
+
+      @notification_worker = Wait.spawn("acp-notifications") do
+        while (message = @notification_queue.pop)
+          if message.is_a?(Wait::Latch)
+            message.open
+          else
+            run_notification(message)
+          end
+        end
+      end
+    end
+
+    def stop_notification_worker
+      worker = @mutex.synchronize do
+        current = @notification_worker
+        @notification_worker = nil
+        current
+      end
+      return unless worker
+
+      begin
+        @notification_queue.push(nil)
+      rescue ::Async::Queue::ClosedError, ClosedQueueError
+        nil
+      end
+      return if Wait.current?(worker)
+
+      Wait.stop(worker) unless Wait.join(worker, @worker_grace)
+    end
+
+    def spawn_worker(name, &block)
+      Wait.spawn(name) do
+        me = Wait.current_worker
+        @mutex.synchronize { @workers << me }
+        begin
+          block.call
+        ensure
+          @mutex.synchronize { @workers.delete(me) }
+        end
+      end
+    end
+
+    def listening?
+      Wait.alive?(@listen_worker)
+    end
+
+    def stop_workers
+      workers = @mutex.synchronize do
+        list = @workers.to_a
+        @workers.clear
+        list
+      end
+      workers.each do |worker|
+        next if Wait.current?(worker)
+
+        Wait.stop(worker) unless Wait.join(worker, @worker_grace)
+      end
+      listener = @listen_worker
+      return if listener.nil? || Wait.current?(listener)
+
+      Wait.stop(listener) unless Wait.join(listener, @worker_grace)
+    end
+  end
+end

data/lib/acp/exceptions.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ACP
+  class Error < StandardError; end
+
+  class RequestError < Error
+    attr_reader :code, :data
+
+    def initialize(code, message, data = nil)
+      super(message)
+      @code = code
+      @data = data
+    end
+
+    def self.parse_error(data = nil)        = new(-32700, "Parse error", data)
+    def self.invalid_request(data = nil)     = new(-32600, "Invalid request", data)
+    def self.method_not_found(method)        = new(-32601, "Method not found", { "method" => method })
+    def self.invalid_params(data = nil)      = new(-32602, "Invalid params", data)
+    def self.internal_error(data = nil)      = new(-32603, "Internal error", data)
+    def self.request_cancelled(data = nil)   = new(-32800, "Request cancelled", data)
+    def self.auth_required(data = nil)       = new(-32000, "Authentication required", data)
+    def self.resource_not_found(uri = nil)   = new(-32002, "Resource not found", uri ? { "uri" => uri } : nil)
+
+    def to_error_obj
+      { "code" => @code, "message" => message, "data" => @data }
+    end
+  end
+
+  class ConnectionError < Error; end
+
+  class TimeoutError < Error; end
+end

data/lib/acp/meta.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ACP
+  PROTOCOL_VERSION = 1
+  SCHEMA_REF = "refs/tags/schema-v1.21.0"
+
+  AGENT_METHODS = {
+    "initialize" => "initialize",
+    "authenticate" => "authenticate",
+    "providers_list" => "providers/list",
+    "providers_set" => "providers/set",
+    "providers_disable" => "providers/disable",
+    "session_new" => "session/new",
+    "session_load" => "session/load",
+    "session_set_mode" => "session/set_mode",
+    "session_set_config_option" => "session/set_config_option",
+    "session_prompt" => "session/prompt",
+    "session_cancel" => "session/cancel",
+    "mcp_message" => "mcp/message",
+    "session_list" => "session/list",
+    "session_delete" => "session/delete",
+    "session_fork" => "session/fork",
+    "session_resume" => "session/resume",
+    "session_close" => "session/close",
+    "logout" => "logout",
+    "nes_start" => "nes/start",
+    "nes_suggest" => "nes/suggest",
+    "nes_accept" => "nes/accept",
+    "nes_reject" => "nes/reject",
+    "nes_close" => "nes/close",
+    "document_did_open" => "document/didOpen",
+    "document_did_change" => "document/didChange",
+    "document_did_close" => "document/didClose",
+    "document_did_save" => "document/didSave",
+    "document_did_focus" => "document/didFocus"
+  }.freeze
+
+  CLIENT_METHODS = {
+    "session_request_permission" => "session/request_permission",
+    "session_update" => "session/update",
+    "fs_write_text_file" => "fs/write_text_file",
+    "fs_read_text_file" => "fs/read_text_file",
+    "terminal_create" => "terminal/create",
+    "terminal_output" => "terminal/output",
+    "terminal_release" => "terminal/release",
+    "terminal_wait_for_exit" => "terminal/wait_for_exit",
+    "terminal_kill" => "terminal/kill",
+    "mcp_connect" => "mcp/connect",
+    "mcp_message" => "mcp/message",
+    "mcp_disconnect" => "mcp/disconnect",
+    "elicitation_create" => "elicitation/create",
+    "elicitation_complete" => "elicitation/complete"
+  }.freeze
+
+  PROTOCOL_METHODS = {
+    "cancel_request" => "$/cancel_request"
+  }.freeze
+end

data/lib/acp/router.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "exceptions"
+require_relative "schema_base"
+
+module ACP
+  class Route
+    attr_reader :method, :kind
+
+    def initialize(method:, handler:, kind:, model: nil, optional: false, default_result: nil, adapt_result: nil)
+      @method = method
+      @handler = handler
+      @kind = kind
+      @model = model
+      @optional = optional
+      @default_result = default_result
+      @adapt_result = adapt_result
+    end
+
+    def handle(params)
+      unless @handler
+        return @default_result if @optional
+
+        raise RequestError.method_not_found(@method)
+      end
+
+      argument = @model ? @model.coerce(params.nil? ? {} : params) : params
+      result = @handler.call(argument)
+      return result unless @kind == :request && @adapt_result
+
+      @adapt_result.call(result)
+    end
+  end
+
+  class Router
+    NORMALIZE_RESULT = ->(result) { result.nil? ? {} : result }
+
+    def initialize
+      @requests = {}
+      @notifications = {}
+      @extension_request = nil
+      @extension_notification = nil
+    end
+
+    def add_route(route)
+      if route.kind == :request
+        @requests[route.method] = route
+      else
+        @notifications[route.method] = route
+      end
+      route
+    end
+
+    def route_request(method, model, target, *names, optional: false, default_result: nil, normalize: false)
+      handler = resolve_handler(target, names)
+      add_route(Route.new(
+        method: method,
+        handler: handler,
+        kind: :request,
+        model: model,
+        optional: optional,
+        default_result: default_result,
+        adapt_result: normalize ? NORMALIZE_RESULT : nil
+      ))
+    end
+
+    def route_notification(method, model, target, *names)
+      handler = resolve_handler(target, names)
+      add_route(Route.new(
+        method: method,
+        handler: handler,
+        kind: :notification,
+        model: model,
+        optional: true
+      ))
+    end
+
+    def on_extension_request(&block)
+      @extension_request = block
+    end
+
+    def on_extension_notification(&block)
+      @extension_notification = block
+    end
+
+    def requests
+      @requests.keys
+    end
+
+    def notifications
+      @notifications.keys
+    end
+
+    def call(method, params, is_notification)
+      if method.start_with?("_")
+        handler = is_notification ? @extension_notification : @extension_request
+        return nil if is_notification && handler.nil?
+        raise RequestError.method_not_found(method) unless handler
+
+        return handler.call(method[1..], params.is_a?(Hash) ? params : {})
+      end
+
+      routes = is_notification ? @notifications : @requests
+      route = routes[method]
+      raise RequestError.method_not_found(method) unless route
+
+      route.handle(params)
+    end
+
+    private
+
+    def resolve_handler(target, names)
+      name = names.flatten.find { |candidate| target.respond_to?(candidate) }
+      return nil unless name
+
+      target.method(name)
+    end
+  end
+end