acp-sdk 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96418a5250fccc2c0eb4380e15309f7658f347bc91d5df3c1218cc3794389f48
-  data.tar.gz: 52c089fd1c4238da195880f4fcbf823452272de94a6c3f6ad3a2d7c06f0580d1
+  metadata.gz: 25494cd3370ba23c2d4e0055acbe0cc5ca7c30dba75abdb58ed1c5a9659ba471
+  data.tar.gz: 71522f1fd9a8bf5370f97719a78bd88149c9dfecbaa986031788693cde1e1c88
 SHA512:
-  metadata.gz: 84820ff6950c13e9d2fd30f5e5936f7951700af3622bfdc84af49cfcd6b7f24465e00d4889d2d451eaa01fc5091b6af7ecc103579c175d683f451e7ac27a86ce
-  data.tar.gz: 696efcc33f82fd2bc5ecd1a8e9843138c5be690e13ed4a72c955202c95af404c43a7c794868a1a0dad712174bb6ceaf71b0ab9d51bcf86e5954f6f6acdee3d61
+  metadata.gz: a29109841f97f7de1f5c1951e82379179741ba08100e6514949a17033e85b646eb35781b7bf01f26eb754831e510bb7de07be13cf0fa02d0817b102f5f370097
+  data.tar.gz: 594b91f54fb5722b3d884d210e485606c13a7902f1300e4fe42a467d1b2ed5725b087ad12346b4fe4e46df3fbf2d0a1d82100e6ea47091237f5017755f4264f3

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.12.0](https://github.com/bottrall/acp-sdk/compare/v0.11.0...v0.12.0) (2026-10-13)
+
+
+### Features
+
+* add RequestError#connection_closed? predicate ([#145](https://github.com/bottrall/acp-sdk/issues/145)) ([16692be](https://github.com/bottrall/acp-sdk/commit/16692be92531e2ddbf14d6547a1bbb431cc151d3)), closes [#108](https://github.com/bottrall/acp-sdk/issues/108)
+* expose Stdio serving state and drain ([#148](https://github.com/bottrall/acp-sdk/issues/148)) ([e8169c1](https://github.com/bottrall/acp-sdk/commit/e8169c1902d8f8ab185cc809e14f08ea98300007)), closes [#107](https://github.com/bottrall/acp-sdk/issues/107)
+
 ## [0.11.0](https://github.com/bottrall/acp-sdk/compare/v0.10.0...v0.11.0) (2026-10-12)
 
 

data/README.md

@@ -58,9 +58,12 @@ The agent's contract:
 - `client.read_text_file` and `client.write_text_file` take an `ACP::Types::ReadTextFileRequest` or `ACP::Types::WriteTextFileRequest` and return the response type or an `ACP::RequestError`. Unless `client.capabilities` advertises `fs.read_text_file` or `fs.write_text_file`, they return `-32601` without sending anything to the client.
 - `client.create_terminal`, `client.terminal_output`, `client.wait_for_terminal_exit`, `client.kill_terminal` and `client.release_terminal` take the matching `ACP::Types` request (`CreateTerminalRequest`, `TerminalOutputRequest`, `WaitForTerminalExitRequest`, `KillTerminalRequest`, `ReleaseTerminalRequest`) and return its response type or an `ACP::RequestError`. Unless `client.capabilities` advertises `terminal`, they return `-32601` without sending anything to the client. The agent must release every terminal it creates.
 - `client.create_elicitation` takes an `ACP::Types::CreateElicitationRequest` and returns an `ACP::Types::CreateElicitationResponse` or an `ACP::RequestError`. Unless `client.capabilities` advertises the `elicitation.form` or `elicitation.url` mode the request asks for, it returns `-32601` without sending anything to the client. A response action the SDK does not know comes through as the raw hash the client sent. `client.complete_elicitation` takes an `ACP::Types::CompleteElicitationNotification` and sends nothing, returning `-32601`, unless the client advertises `elicitation.url`, since only URL-mode elicitations are completed.
+- Once the transport's input ends, a `client` request still waiting for its answer and every one made afterwards return an `ACP::RequestError` whose `connection_closed?` is true. It is false for every error the client sent, even one with the same `-32603` code and `Connection closed` message, so a handler can tell a client that is gone from one that refused without matching the message.
 
 Extensions are `_`-prefixed methods outside the spec. `AgentConnection` takes `extension_requests` and `extension_notifications` hashes keyed by the raw wire name, and `client.ext_request` and `client.ext_notify` send them to the client; a handler name without the `_` prefix raises `ArgumentError`, and an extension request with no handler is answered with `-32601`.
 
+An embedder that manages the connection's lifecycle keeps a reference to the transport it built: `transport.serving_ids` returns the ids of the requests whose handlers are still running, and `transport.drain` blocks, with no timeout, until those handlers have replied and any `session_created` hook has run. `drain` waits only for the requests in flight when it is called, so join the reader thread `start` returns first — once the client hangs up nothing new arrives — and close the IOs after it returns. A write after either end of the output has closed is logged to the transport's logger as a warning and dropped rather than raised.
+
 [`examples/echo_agent.rb`](https://github.com/bottrall/acp-sdk/blob/main/examples/echo_agent.rb) is a complete agent that streams updates, asks permission, handles cancellation, reads and writes files and runs commands through the client (`/read <path>`, `/write <path> <text>` and `/run <command> [args]`, each advertised as a slash command only when the client supports it), and supports `session/load`, `session/list`, `session/resume`, `session/close` and `session/delete`.
 
 ## Driving an agent
@@ -110,6 +113,7 @@ connection = ACP::ClientConnection.new(
 - `read_text_file` and `write_text_file` answer the agent's `fs/read_text_file` and `fs/write_text_file` with an `ACP::Types::ReadTextFileResponse`, an `ACP::Types::WriteTextFileResponse` or an `ACP::RequestError`. They are routed by the `fs` capabilities `connect` sends: a method the client does not advertise is answered with `-32601` without reaching the handler, and `connect` raises `ArgumentError` — before sending `initialize` — when the request advertises a capability that has no handler.
 - `create_terminal`, `terminal_output`, `wait_for_terminal_exit`, `kill_terminal` and `release_terminal` answer the agent's `terminal/create`, `terminal/output`, `terminal/wait_for_exit`, `terminal/kill` and `terminal/release` with the matching `ACP::Types` response or an `ACP::RequestError`. They are routed by the `terminal` capability `connect` sends, the same way as `fs`: a method the client does not advertise is answered with `-32601` without reaching the handler, and `connect` raises `ArgumentError` — before sending `initialize` — when the request advertises `terminal` with any of the five missing. The transport serves each request on its own thread, so `wait_for_terminal_exit` may block without holding up the others.
 - `elicitation` answers the agent's `elicitation/create` with an `ACP::Types::CreateElicitationResponse` or an `ACP::RequestError`, serving both form and url mode, and `complete_elicitation` receives the agent's `elicitation/complete` notification. They are routed by the `elicitation` capabilities `connect` sends: a request whose mode the client does not advertise is answered with `-32602` without reaching the handler, and `connect` raises `ArgumentError` — before sending `initialize` — when the request advertises `elicitation.form` or `elicitation.url` with no `elicitation` handler. The client tracks the elicitation ids of the url-mode requests it serves, so a completion for an unknown or already-completed id is ignored. `complete_elicitation` runs on the reader thread and must return quickly; it may be omitted, in which case completions are only tracked.
+- Once the transport's input ends, a request still waiting for its answer and every one made afterwards return an `ACP::RequestError` whose `connection_closed?` is true. It is false for every error the agent sent, so a closed agent is told apart from a refusal without matching the message.
 
 Extensions work the same way in both directions: `extension_requests` and `extension_notifications` are hashes keyed by the raw `_`-prefixed wire name, `ext_request` sends one to the agent and returns its result as-is, and `ext_notify` sends an extension notification. A handler name without the `_` prefix raises `ArgumentError`, and an extension request nothing answers gets `-32601`.
 

data/lib/acp/request_error.rb

@@ -36,6 +36,16 @@ class ACP::RequestError
     { 'code' => code, 'message' => message, 'data' => data }.compact
   end
 
+  CONNECTION_CLOSED = new(code: INTERNAL_ERROR, message: 'Connection closed') #: ACP::RequestError
+
+  # Identity rather than code and message: a live peer can answer with the
+  # same pair, and that refusal must not read as a closed connection.
+  #
+  # @rbs return: bool
+  def connection_closed?
+    equal?(CONNECTION_CLOSED)
+  end
+
   # @rbs return: ACP::RequestError
   def self.parse_error
     new(code: PARSE_ERROR, message: 'Parse error')

data/lib/acp/transport/stdio/serving.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class ACP::Transport::Stdio::Serving
+  # @dynamic id
+  attr_reader :id #: untyped
+
+  # @dynamic cancellation
+  attr_reader :cancellation #: ACP::Transport::Cancellation
+
+  # @rbs id: untyped
+  # @rbs cancellation: ACP::Transport::Cancellation
+  # @rbs return: void
+  def initialize(id:, cancellation:)
+    @id = id
+    @cancellation = cancellation
+    freeze
+  end
+end

data/lib/acp/transport/stdio.rb

@@ -12,14 +12,12 @@ class ACP::Transport::Stdio
   # @rbs @write_lock: Thread::Mutex
   # @rbs @lock: Thread::Mutex
   # @rbs @pending: Hash[untyped, Thread::Queue]
-  # @rbs @serving: Hash[untyped, ACP::Transport::Cancellation]
+  # @rbs @serving: Hash[Thread, ACP::Transport::Stdio::Serving]
   # @rbs @next_id: Integer
   # @rbs @closed: bool
   # @rbs @logger: ACP::Transport::_Logger
 
-  CONNECTION_CLOSED = ACP::RequestError.new(
-    code: ACP::RequestError::INTERNAL_ERROR, message: 'Connection closed'
-  ) #: ACP::RequestError
+  CONNECTION_CLOSED = ACP::RequestError::CONNECTION_CLOSED #: ACP::RequestError
 
   # @rbs input: _Reader
   # @rbs output: _Writer
@@ -37,6 +35,13 @@ class ACP::Transport::Stdio
     @logger = logger
   end
 
+  # Joining the returned thread does not wait for the requests still being
+  # served. EOF cancels none of them (only the peer's $/cancel_request does):
+  # each handler runs to completion and its reply is still written, to be
+  # warned and dropped if the peer is gone. A caller blocked in #request, a
+  # handler waiting on its own request included, is released with
+  # CONNECTION_CLOSED.
+  #
   # @rbs requests: Hash[String, _Handler]
   # @rbs notifications: Hash[String, _NotificationHandler]
   # @rbs return: Thread
@@ -93,6 +98,19 @@ class ACP::Transport::Stdio
     ACP::Transport::Cancellation.current
   end
 
+  # @rbs return: Array[untyped]
+  def serving_ids
+    @lock.synchronize { @serving.each_value.map(&:id) }
+  end
+
+  # Joins the requests in flight at the call, not one the reader dispatches
+  # meanwhile: join the reader thread first to leave nothing in flight.
+  #
+  # @rbs return: void
+  def drain
+    @lock.synchronize { @serving.keys }.each(&:join)
+  end
+
   private
 
   # @rbs line: String
@@ -167,39 +185,29 @@ class ACP::Transport::Stdio
   # @rbs method: String
   # @rbs return: void
   def serve(handler, id, params, method)
-    cancellation = register_serving(id)
-    Thread.new do
-      ACP::Transport::Cancellation.current = cancellation
-      outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
-      case outcome
-      when ACP::Transport::Reply
-        reply(id, outcome.result)
-        quietly('reply after callback', &outcome.after)
-      else reply(id, outcome)
+    cancellation = ACP::Transport::Cancellation.new
+    # Registered on the reader thread so a cancel racing the request cannot
+    # be missed. The serve thread starts under the lock so it is registered
+    # before a drain can miss it or it can unregister itself.
+    @lock.synchronize do
+      thread = Thread.new do
+        ACP::Transport::Cancellation.current = cancellation
+        outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
+        case outcome
+        when ACP::Transport::Reply
+          reply(id, outcome.result)
+          quietly('reply after callback', &outcome.after)
+        else reply(id, outcome)
+        end
+      ensure
+        # Unregistered only after the reply and its after callback, so drain waits
+        # for both and later cancels for the id are ignored.
+        @lock.synchronize { @serving.delete(Thread.current) }
       end
-    ensure
-      unregister_serving(id)
+      @serving[thread] = Serving.new(id:, cancellation:)
     end
   end
 
-  # Registered before the serve thread starts so a cancel racing the request
-  # cannot be missed, and dropped once the response is on the wire so later
-  # cancels for the id are ignored.
-  #
-  # @rbs id: untyped
-  # @rbs return: ACP::Transport::Cancellation
-  def register_serving(id)
-    cancellation = ACP::Transport::Cancellation.new
-    @lock.synchronize { @serving[id] = cancellation }
-    cancellation
-  end
-
-  # @rbs id: untyped
-  # @rbs return: void
-  def unregister_serving(id)
-    @lock.synchronize { @serving.delete(id) }
-  end
-
   # A notification has no reply to carry a malformed params failure, so one
   # is warned and dropped rather than answered.
   #
@@ -211,8 +219,10 @@ class ACP::Transport::Stdio
       return @logger.warn('dropped malformed $/cancel_request: missing requestId')
     end
 
-    cancellation = @lock.synchronize { @serving[id] }
-    cancellation&.cancel
+    cancellations = @lock.synchronize do
+      @serving.each_value.filter_map { |entry| entry.cancellation if entry.id == id }
+    end
+    cancellations.each(&:cancel)
   end
 
   # For code with no reply to carry an error: a notification handler, or a
@@ -273,6 +283,9 @@ class ACP::Transport::Stdio
     @lock.synchronize { @pending.delete(id) }&.tap { |queue| queue.push(result) }
   end
 
+  # Leaves @serving alone on purpose: embedders rely on in-flight handlers
+  # running to completion after the input ends.
+  #
   # @rbs return: void
   def close
     @lock.synchronize do
@@ -282,8 +295,9 @@ class ACP::Transport::Stdio
     end
   end
 
-  # A closed peer must not kill the thread writing the reply: the reader has
-  # to keep draining input so pending requests still settle at EOF.
+  # A closed peer (EPIPE) or an output the embedder already closed (IOError)
+  # must not kill the thread writing the reply: the reader has to keep
+  # draining input so pending requests still settle at EOF.
   #
   # @rbs message: Hash[String, untyped]
   # @rbs return: void
@@ -293,7 +307,7 @@ class ACP::Transport::Stdio
       @output.write(line)
       @output.flush
     end
-  rescue Errno::EPIPE => e
+  rescue Errno::EPIPE, IOError => e
     @logger.warn("write to closed peer: #{e.class}: #{e.message}")
   end
 end

data/lib/acp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ACP
-  VERSION = '0.11.0'
+  VERSION = '0.12.0'
 end

data/sig/generated/acp/request_error.rbs

@@ -36,6 +36,14 @@ class ACP::RequestError
   # @rbs return: Hash[String, untyped]
   def to_h: () -> Hash[String, untyped]
 
+  CONNECTION_CLOSED: ACP::RequestError
+
+  # Identity rather than code and message: a live peer can answer with the
+  # same pair, and that refusal must not read as a closed connection.
+  #
+  # @rbs return: bool
+  def connection_closed?: () -> bool
+
   # @rbs return: ACP::RequestError
   def self.parse_error: () -> ACP::RequestError
 

data/sig/generated/acp/transport/stdio/serving.rbs

@@ -0,0 +1,14 @@
+# Generated from lib/acp/transport/stdio/serving.rb with RBS::Inline
+
+class ACP::Transport::Stdio::Serving
+  # @dynamic id
+  attr_reader id: untyped
+
+  # @dynamic cancellation
+  attr_reader cancellation: ACP::Transport::Cancellation
+
+  # @rbs id: untyped
+  # @rbs cancellation: ACP::Transport::Cancellation
+  # @rbs return: void
+  def initialize: (id: untyped, cancellation: ACP::Transport::Cancellation) -> void
+end

data/sig/generated/acp/transport/stdio.rbs

@@ -11,7 +11,7 @@ class ACP::Transport::Stdio
 
   @next_id: Integer
 
-  @serving: Hash[untyped, ACP::Transport::Cancellation]
+  @serving: Hash[Thread, ACP::Transport::Stdio::Serving]
 
   @pending: Hash[untyped, Thread::Queue]
 
@@ -31,6 +31,13 @@ class ACP::Transport::Stdio
   # @rbs return: void
   def initialize: (input: _Reader, output: _Writer, ?logger: ACP::Transport::_Logger) -> void
 
+  # Joining the returned thread does not wait for the requests still being
+  # served. EOF cancels none of them (only the peer's $/cancel_request does):
+  # each handler runs to completion and its reply is still written, to be
+  # warned and dropped if the peer is gone. A caller blocked in #request, a
+  # handler waiting on its own request included, is released with
+  # CONNECTION_CLOSED.
+  #
   # @rbs requests: Hash[String, _Handler]
   # @rbs notifications: Hash[String, _NotificationHandler]
   # @rbs return: Thread
@@ -62,6 +69,15 @@ class ACP::Transport::Stdio
   # @rbs return: ACP::Transport::Cancellation?
   def cancellation: () -> ACP::Transport::Cancellation?
 
+  # @rbs return: Array[untyped]
+  def serving_ids: () -> Array[untyped]
+
+  # Joins the requests in flight at the call, not one the reader dispatches
+  # meanwhile: join the reader thread first to leave nothing in flight.
+  #
+  # @rbs return: void
+  def drain: () -> void
+
   private
 
   # @rbs line: String
@@ -95,18 +111,6 @@ class ACP::Transport::Stdio
   # @rbs return: void
   def serve: (_Handler? handler, untyped id, untyped params, String method) -> void
 
-  # Registered before the serve thread starts so a cancel racing the request
-  # cannot be missed, and dropped once the response is on the wire so later
-  # cancels for the id are ignored.
-  #
-  # @rbs id: untyped
-  # @rbs return: ACP::Transport::Cancellation
-  def register_serving: (untyped id) -> ACP::Transport::Cancellation
-
-  # @rbs id: untyped
-  # @rbs return: void
-  def unregister_serving: (untyped id) -> void
-
   # A notification has no reply to carry a malformed params failure, so one
   # is warned and dropped rather than answered.
   #
@@ -147,11 +151,15 @@ class ACP::Transport::Stdio
   # @rbs return: Thread::Queue?
   def settle: (untyped id, untyped result) -> Thread::Queue?
 
+  # Leaves @serving alone on purpose: embedders rely on in-flight handlers
+  # running to completion after the input ends.
+  #
   # @rbs return: void
   def close: () -> void
 
-  # A closed peer must not kill the thread writing the reply: the reader has
-  # to keep draining input so pending requests still settle at EOF.
+  # A closed peer (EPIPE) or an output the embedder already closed (IOError)
+  # must not kill the thread writing the reply: the reader has to keep
+  # draining input so pending requests still settle at EOF.
   #
   # @rbs message: Hash[String, untyped]
   # @rbs return: void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -48,6 +48,7 @@ files:
 - lib/acp/transport/reply.rb
 - lib/acp/transport/stderr_logger.rb
 - lib/acp/transport/stdio.rb
+- lib/acp/transport/stdio/serving.rb
 - lib/acp/types.rb
 - lib/acp/types/agent_auth_capabilities.rb
 - lib/acp/types/agent_capabilities.rb
@@ -405,6 +406,7 @@ files:
 - sig/generated/acp/transport/reply.rbs
 - sig/generated/acp/transport/stderr_logger.rbs
 - sig/generated/acp/transport/stdio.rbs
+- sig/generated/acp/transport/stdio/serving.rbs
 - sig/generated/acp/types.rbs
 - sig/generated/acp/types/agent_auth_capabilities.rbs
 - sig/generated/acp/types/agent_capabilities.rbs