acp_sdk_async 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a87705f9f7fc44a42ab713bc4122e1298c84cd5fa736bab7f605d83ee91fe493
-  data.tar.gz: 05f8fe85747082078abd8963111084d6e8d5fcac56c64afb5e7d4cc9dadf22dc
+  metadata.gz: ec9246d9b39f427c0ce91bc4d9538808c0721f391dd29cef5f0a5cf2856a7328
+  data.tar.gz: 2666f26808cc8401f430c18a5ff47199343ea712c96915bd9325a289de817e93
 SHA512:
-  metadata.gz: '0170289fc4f146993df1a91092643774248cfd86d806cb12ef932788462c4333da1beb24c00dda4c672b0ae3b8d3a14be6c732738ecf459f02e01f170b7218eb'
-  data.tar.gz: 361eb5a9641e852eb48d71bce99a8ca811ba50a364b497f62e13d9490c4456b34133a9e6d4bb4336c6c34e4e9a2335affdbb932e41e249b70faabda88911768f
+  metadata.gz: 130265b9d6ba0d8bc97441e8412732dd7118bf1727712288837ee176d38fbb56aea27534eb235341034d8083ac13f28b2898e98da82767d80f3fda01fbaecb44
+  data.tar.gz: 77b2eebd91c6a8f0572ecdfc16b6e8bfb902b7d643e4210af9cdd311f074967338e2ddb17eaa520ddeca3d731d72e9799bc856775014f8bb6b039317852d9a31

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.0]
+
+### Added
+
+- New `ACP::Contrib` helpers: `ToolCallTracker`, `SessionAccumulator`,
+  `PermissionBroker` (+ `default_permission_options`).
+- `Client#set_config_option` alias for `set_session_config_option`
+  (short alias for the same wire method).
+- `Agent#create_elicitation` now also accepts `message:` + `mode:`
+  kwargs next to the full request hash/model.
+- `Agent#write_text_file` / `#release_terminal` / `#kill_terminal`
+  return `nil` on null responses instead of an empty model.
+- RuboCop config (`rake rubocop`), SimpleCov gate (90% minimum),
+  GitHub Actions matrix (Ruby 3.2, 3.3, 3.4, 4.0).
+
+### Fixed
+
+- Works with any `async` 2.x: task cancellation supports both
+  `Async::Stop` (older) and `Async::Cancel` (newer); timed join no
+  longer relies on `Task#wait(timeout:)`. Previously `close` could
+  hang forever on older async releases.
+- `MemoryTransport#close` signals EOF to the peer only; local reads
+  drain queued messages first.
+- `NdjsonTransport` receive timeout now covers partial lines
+  (previously a line without `\n` hung forever).
+- Outgoing observer events fire after a successful send and receive a
+  deep copy, so observers can neither see unsent payloads nor mutate
+  the wire format.
+- `handle_response` prefers `result` over `error` when both are present
+  and resolves `nil` when neither is present.
+- Parallel shutdown of handler tasks instead of sequential grace waits.
+- `Router` no longer coerces missing (`nil`) params to `{}`; they fail
+  validation as `invalid_params` instead of being silently replaced.
+- Schema models validate `required` fields in `.new`, reject
+  catch-all `Other*` values reserved by known variants
+  (`action: accept`, `mode: form`, …), and apply `default_on_error`
+  on direct construction too.
+- Schema generator output is byte-identical on every Ruby
+  (`Hash#inspect` spacing changed in Ruby 3.4).
+
+### Compatibility
+
+- Verified: full suite (189 tests) green on Ruby 3.2, 3.3, 3.4 and 4.0,
+  with `async` 2.37 and 2.45.
+
+## [0.2.0]
+
+- Initial Ruby SDK snapshot: typed schema models, JSON-RPC connection
+  over NDJSON, client/agent wrappers, stdio process management.

data/README.md

@@ -4,6 +4,8 @@ Ruby SDK for the [Agent Client Protocol](https://agentclientprotocol.com) (ACP):
 
 Requires Ruby 3.2+ and runs on [`async`](https://github.com/socketry/async), the same cooperative scheduler used by Falcon. The public API is blocking (`client.prompt(...)`) like a normal Ruby method; inside a reactor those calls yield to other tasks instead of occupying a thread.
 
+Inspired by the [official Python ACP SDK](https://github.com/agentclientprotocol/python-sdk).
+
 ## Installation
 
 ```ruby

data/lib/acp/agent.rb

@@ -108,7 +108,7 @@ module ACP
       end
 
       def write_text_file(session_id:, path:, content:, **meta)
-        request(
+        request_optional(
           CLIENT_METHODS["fs_write_text_file"], Schema::WriteTextFileRequest, Schema::WriteTextFileResponse,
           session_id: session_id, path: path, content: content, **meta
         )
@@ -130,7 +130,7 @@ module ACP
       end
 
       def release_terminal(session_id:, terminal_id:, **meta)
-        request(
+        request_optional(
           CLIENT_METHODS["terminal_release"], Schema::ReleaseTerminalRequest, Schema::ReleaseTerminalResponse,
           session_id: session_id, terminal_id: terminal_id, **meta
         )
@@ -145,14 +145,25 @@ module ACP
       end
 
       def kill_terminal(session_id:, terminal_id:, **meta)
-        request(
+        request_optional(
           CLIENT_METHODS["terminal_kill"], Schema::KillTerminalRequest, Schema::KillTerminalResponse,
           session_id: session_id, terminal_id: terminal_id, **meta
         )
       end
 
-      def create_elicitation(request)
-        payload = Schema::CreateElicitationRequest.coerce(request)
+      # Accepts either a full request model/hash or message:+mode: kwargs.
+      # Mode is one of ElicitationFormSessionMode / ElicitationFormRequestMode /
+      # ElicitationUrlSessionMode / ElicitationUrlRequestMode.
+      def create_elicitation(request = nil, message: nil, mode: nil, **meta)
+        payload =
+          if !message.nil? || !mode.nil?
+            raise ArgumentError, "message: and mode: are both required" if message.nil? || mode.nil?
+            raise ArgumentError, "request must not be given with message:/mode:" unless request.nil?
+
+            build_elicitation_request(message, mode, meta)
+          else
+            Schema::CreateElicitationRequest.coerce(request)
+          end
         result = @conn.send_request(CLIENT_METHODS["elicitation_create"], payload)
         Schema::CreateElicitationResponse.coerce(result || {})
       end
@@ -178,6 +189,16 @@ module ACP
         response_class.coerce(result || {})
       end
 
+      # Optional responses: null / non-dict responses become nil
+      # instead of an empty model.
+      def request_optional(method, request_class, response_class, **kwargs)
+        payload = build(request_class, kwargs)
+        result = @conn.send_request(method, payload)
+        return nil unless result.is_a?(Hash)
+
+        response_class.coerce(result)
+      end
+
       def notify(method, request_class, **kwargs)
         @conn.send_notification(method, build(request_class, kwargs))
       end
@@ -188,6 +209,27 @@ module ACP
         model.field_meta = meta if meta
         model
       end
+
+      def build_elicitation_request(message, mode, meta)
+        mode_hash = mode.is_a?(Schema::Base) ? mode.to_h : Schema.serialize(mode)
+        mode_hash = mode_hash.transform_keys(&:to_s)
+        field_meta = meta.delete(:field_meta) || meta.delete(:meta)
+        # The mode models carry no "mode" discriminator (it lives on the
+        # request), so infer it from the mode class.
+        discriminator =
+          case mode
+          when Schema::ElicitationFormSessionMode, Schema::ElicitationFormRequestMode then "form"
+          when Schema::ElicitationUrlSessionMode, Schema::ElicitationUrlRequestMode then "url"
+          else mode_hash["mode"]
+          end
+        # Merge message + mode fields; the CreateElicitationRequest union
+        # dispatches to the correct form/url variant.
+        hash = { "message" => message }.merge(mode_hash).merge(meta.compact.transform_keys(&:to_s))
+        hash["mode"] = discriminator if discriminator
+        request = Schema::CreateElicitationRequest.coerce(hash)
+        request.field_meta = field_meta if field_meta
+        request
+      end
     end
 
     def self.run_agent(agent, input: $stdin, output: $stdout, **connection_options)

data/lib/acp/client.rb

@@ -152,7 +152,7 @@ module ACP
       end
 
       def set_session_config_option(session_id:, config_id:, value:, **meta)
-        request_class = if value == true || value == false
+        request_class = if [true, false].include?(value)
                           Schema::SetSessionConfigOptionBooleanRequest
                         else
                           Schema::SetSessionConfigOptionSelectRequest
@@ -163,6 +163,9 @@ module ACP
         )
       end
 
+      # Short alias for the same wire method (session/set_config_option).
+      alias set_config_option set_session_config_option
+
       def prompt(session_id:, prompt:, **meta)
         request(AGENT_METHODS["session_prompt"], Schema::PromptRequest, Schema::PromptResponse,
                 session_id: session_id, prompt: prompt, **meta)

data/lib/acp/connection.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require "set"
 require "async/queue"
 require_relative "exceptions"
 require_relative "schema_base"
@@ -34,7 +33,7 @@ module ACP
     end
 
     def closed?
-      @closed
+      @mutex.synchronize { @closed }
     end
 
     def add_observer(callable = nil, &block)
@@ -74,11 +73,15 @@ module ACP
     end
 
     def send_request(method, params = nil, timeout: nil)
-      raise ConnectionError, "Connection closed" if @closed
-
-      request_id = next_id
+      request_id = nil
       promise = Wait::Promise.new
-      @mutex.synchronize { @pending[request_id] = promise }
+      @mutex.synchronize do
+        raise ConnectionError, "Connection closed" if @closed
+
+        request_id = @next_id
+        @next_id += 1
+        @pending[request_id] = promise
+      end
 
       payload = { "jsonrpc" => "2.0", "id" => request_id, "method" => method }
       payload["params"] = serialize(params) unless params.nil?
@@ -99,7 +102,7 @@ module ACP
     end
 
     def send_notification(method, params = nil)
-      raise ConnectionError, "Connection closed" if @closed
+      @mutex.synchronize { raise ConnectionError, "Connection closed" if @closed }
 
       payload = { "jsonrpc" => "2.0", "method" => method }
       payload["params"] = serialize(params) unless params.nil?
@@ -110,14 +113,23 @@ module ACP
       return true unless Wait.alive?(@notification_worker)
 
       latch = Wait::Latch.new
-      @notification_queue.push(latch)
+      begin
+        @notification_queue.push(latch)
+      rescue ::Async::Queue::ClosedError
+        return false
+      end
       latch.wait(timeout)
     end
 
     def close
-      return if @closed
+      already_closed = @mutex.synchronize do
+        next true if @closed
+
+        @closed = true
+        false
+      end
+      return if already_closed
 
-      @closed = true
       reject_all(ConnectionError.new("Connection closed"))
       begin
         @transport.close
@@ -143,13 +155,15 @@ module ACP
     end
 
     def write(payload)
-      notify_observers(:outgoing, payload)
+      # Notify AFTER successful send: notifying before would expose observers
+      # to messages that never hit the wire and let them mutate the payload.
       @transport.send_message(payload)
+      notify_observers(:outgoing, payload)
     end
 
     def receive_loop
       loop do
-        break if @closed
+        break if closed?
 
         message = begin
           @transport.receive_message
@@ -159,7 +173,7 @@ module ACP
         rescue ConnectionError => e
           ACP.logger.debug("acp: receive failed: #{e.message}")
           break
-        rescue ::Async::Cancel
+        rescue Wait::TASK_STOPPED
           break
         end
         break if message.nil?
@@ -210,7 +224,7 @@ module ACP
         payload["error"] = RequestError.invalid_params(
           "errors" => [{ "message" => e.message, "loc" => e.path }]
         ).to_error_obj
-      rescue ::Async::Cancel
+      rescue Wait::TASK_STOPPED
         return
       rescue StandardError => e
         ACP.logger.error("acp: handler for #{message['method']} failed: #{e.class}: #{e.message}")
@@ -219,19 +233,19 @@ module ACP
       write(payload)
     rescue ConnectionError => e
       ACP.logger.debug("acp: could not send response for #{message['method']}: #{e.message}")
-    rescue ::Async::Cancel
+    rescue Wait::TASK_STOPPED
       nil
     end
 
     def respond_error(id, error)
       write({ "jsonrpc" => "2.0", "id" => id, "error" => error.to_error_obj })
-    rescue ConnectionError, ::Async::Cancel
+    rescue ConnectionError, Wait::TASK_STOPPED
       nil
     end
 
     def run_notification(message)
       @handler.call(message["method"], message["params"], true)
-    rescue ::Async::Cancel
+    rescue Wait::TASK_STOPPED
       nil
     rescue StandardError => e
       ACP.logger.error("acp: notification handler for #{message['method']} failed: #{e.class}: #{e.message}")
@@ -243,12 +257,18 @@ module ACP
         ACP.logger.debug("acp: response for unknown request id #{message['id'].inspect}")
         return
       end
+      return if promise.settled?
 
-      if message.key?("error")
+      # JSON-RPC result and error are mutually exclusive; when both are present
+      # prefer result.
+      if message.key?("result")
+        promise.resolve(message["result"])
+      elsif message.key?("error")
         error = message["error"] || {}
+        error = {} unless error.is_a?(Hash)
         promise.reject(RequestError.new(error["code"] || -32603, error["message"] || "Error", error["data"]))
       else
-        promise.resolve(message["result"])
+        promise.resolve(nil)
       end
     end
 
@@ -258,14 +278,30 @@ module ACP
         @pending.clear
         items
       end
-      pending.each { |promise| promise.reject(error) }
+      pending.each do |promise|
+        promise.reject(error) unless promise.settled?
+      rescue StandardError
+        nil
+      end
+    end
+
+    def deep_copy_message(message)
+      JSON.parse(JSON.generate(message))
+    rescue StandardError
+      begin
+        Marshal.load(Marshal.dump(message))
+      rescue StandardError
+        message.is_a?(Hash) ? message.dup : message
+      end
     end
 
     def notify_observers(direction, message)
       observers = @mutex.synchronize { @observers.dup }
       return if observers.empty?
 
-      event = StreamEvent.new(direction: direction, message: message)
+      # Deep-copy once so observers cannot mutate the wire payload.
+      snapshot = deep_copy_message(message)
+      event = StreamEvent.new(direction: direction, message: snapshot)
       observers.each do |observer|
         observer.call(event)
       rescue StandardError => e
@@ -297,7 +333,7 @@ module ACP
 
       begin
         @notification_queue.push(nil)
-      rescue ::Async::Queue::ClosedError, ClosedQueueError
+      rescue ::Async::Queue::ClosedError
         nil
       end
       return if Wait.current?(worker)
@@ -306,6 +342,8 @@ module ACP
     end
 
     def spawn_worker(name, &block)
+      return nil if closed?
+
       Wait.spawn(name) do
         me = Wait.current_worker
         @mutex.synchronize { @workers << me }
@@ -327,11 +365,12 @@ module ACP
         @workers.clear
         list
       end
-      workers.each do |worker|
-        next if Wait.current?(worker)
-
-        Wait.stop(worker) unless Wait.join(worker, @worker_grace)
-      end
+      # Stop all first, then join: parallel shutdown instead of N * grace.
+      # rubocop:disable Style/CombinableLoops -- merging the loops would serialize stop+join per worker
+      pending = workers.reject { |worker| Wait.current?(worker) }
+      pending.each { |worker| Wait.stop(worker) }
+      pending.each { |worker| Wait.join(worker, @worker_grace) }
+      # rubocop:enable Style/CombinableLoops
       listener = @listen_worker
       return if listener.nil? || Wait.current?(listener)
 

data/lib/acp/contrib/permissions.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../schema"
+require_relative "tool_calls"
+
+module ACP
+  module Contrib
+    class PermissionBrokerError < StandardError; end
+
+    class MissingToolCallError < PermissionBrokerError
+      def initialize
+        super("tool_call must be provided when no ToolCallTracker is configured")
+      end
+    end
+
+    class MissingPermissionOptionsError < PermissionBrokerError
+      def initialize
+        super("PermissionBroker requires at least one permission option")
+      end
+    end
+
+    def self.default_permission_options
+      [
+        Schema::PermissionOption.new(option_id: "approve", name: "Approve", kind: "allow_once"),
+        Schema::PermissionOption.new(option_id: "approve_for_session", name: "Approve for session", kind: "allow_always"),
+        Schema::PermissionOption.new(option_id: "reject", name: "Reject", kind: "reject_once")
+      ]
+    end
+
+    # Helper for issuing permission requests tied to tracked tool calls.
+    # The requester is a sync callable: response = requester.call(request).
+    class PermissionBroker
+      def initialize(session_id, requester, tracker: nil, default_options: nil)
+        @session_id = session_id
+        @requester = requester
+        @tracker = tracker
+        @default_options = (default_options || Contrib.default_permission_options).map do |option|
+          Contrib.deep_copy_model(option)
+        end
+      end
+
+      def request_for(external_id, description: nil, options: nil, content: nil, tool_call: nil)
+        resolved =
+          if tool_call.nil?
+            raise MissingToolCallError if @tracker.nil?
+
+            @tracker.tool_call_model(external_id)
+          else
+            Contrib.deep_copy_model(tool_call)
+          end
+
+        resolved.content = Contrib.copy_model_list(content) unless content.nil?
+
+        if description
+          existing = resolved.content || []
+          existing << Schema::ContentToolCallContent.new(
+            content: Schema::TextContentBlock.new(text: description)
+          )
+          resolved.content = existing
+        end
+
+        option_set = (options || @default_options).map { |option| Contrib.deep_copy_model(option) }
+        raise MissingPermissionOptionsError if option_set.empty?
+
+        request = Schema::RequestPermissionRequest.new(
+          session_id: @session_id,
+          tool_call: resolved,
+          options: option_set
+        )
+        @requester.call(request)
+      end
+    end
+  end
+end