acp-sdk 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0d983006184ce11ac51e9361062aa6878c01d348645f41fe226423db5d72e8b
-  data.tar.gz: 0d50ff69cb0c6cc743d75dcd3fd943a9ddeaa4469a8f1e8d6e54be811e3c3b39
+  metadata.gz: 25494cd3370ba23c2d4e0055acbe0cc5ca7c30dba75abdb58ed1c5a9659ba471
+  data.tar.gz: 71522f1fd9a8bf5370f97719a78bd88149c9dfecbaa986031788693cde1e1c88
 SHA512:
-  metadata.gz: 4296fbbf1fa985cb3913f2019528c06658fd8fcac285a238abf79073d2d5eb13d081e69da57f05476569967189f732c804f6dc851e291709c0b4052572b17d9f
-  data.tar.gz: 8f0a5bedfa32615f867111297c4fc593f2b567fd77a55e76dda4eabe57bd8494e225de93b470f1ac294f4b99a57797fda4d7f69704693fb8cd322e65fe650f59
+  metadata.gz: a29109841f97f7de1f5c1951e82379179741ba08100e6514949a17033e85b646eb35781b7bf01f26eb754831e510bb7de07be13cf0fa02d0817b102f5f370097
+  data.tar.gz: 594b91f54fb5722b3d884d210e485606c13a7902f1300e4fe42a467d1b2ed5725b087ad12346b4fe4e46df3fbf2d0a1d82100e6ea47091237f5017755f4264f3

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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)
+
+
+### Features
+
+* standardize ClientConnection senders on verb-noun naming ([#118](https://github.com/bottrall/acp-sdk/issues/118)) ([1b844ec](https://github.com/bottrall/acp-sdk/commit/1b844ecccef5b8714c5e3f2d0299713f0ee09e0f))
+
+
+### Bug Fixes
+
+* answer malformed elicitation params as invalid params ([#133](https://github.com/bottrall/acp-sdk/issues/133)) ([b9e1c51](https://github.com/bottrall/acp-sdk/commit/b9e1c510b60f78986998ba8be56c8a039488ee95)), closes [#125](https://github.com/bottrall/acp-sdk/issues/125)
+* answer the agent when a permission handler raises ([#134](https://github.com/bottrall/acp-sdk/issues/134)) ([a0f61a9](https://github.com/bottrall/acp-sdk/commit/a0f61a9db3589848fafadb7b4e19ad70b260f508)), closes [#124](https://github.com/bottrall/acp-sdk/issues/124)
+* cancel the echo agent's in-flight turn when its session is closed or deleted ([#136](https://github.com/bottrall/acp-sdk/issues/136)) ([e04a8c0](https://github.com/bottrall/acp-sdk/commit/e04a8c0bb672b569d68029c63eaee826d00c84fd)), closes [#130](https://github.com/bottrall/acp-sdk/issues/130)
+* **codegen:** keep the unset sentinel out of clearable to_h conversions ([#140](https://github.com/bottrall/acp-sdk/issues/140)) ([67769d7](https://github.com/bottrall/acp-sdk/commit/67769d7ff5d9f93dfe3f3ea2ba4ac71126caad60)), closes [#131](https://github.com/bottrall/acp-sdk/issues/131)
+* **codegen:** resolve primitive unions from each option's resolved shape ([#141](https://github.com/bottrall/acp-sdk/issues/141)) ([0b574ae](https://github.com/bottrall/acp-sdk/commit/0b574ae9d33c6c10eb0a00866b6c07f1601e01e8)), closes [#132](https://github.com/bottrall/acp-sdk/issues/132)
+* **codegen:** subsume union-variant twins into variant aliases ([#103](https://github.com/bottrall/acp-sdk/issues/103)) ([bdc0005](https://github.com/bottrall/acp-sdk/commit/bdc0005460c0fd133a09f10cf61f9f5717012e16)), closes [#93](https://github.com/bottrall/acp-sdk/issues/93)
+* echo slash commands followed only by whitespace ([#135](https://github.com/bottrall/acp-sdk/issues/135)) ([bb4bde6](https://github.com/bottrall/acp-sdk/commit/bb4bde6951ceb54ac87c92ec335dcdd319fd7b81)), closes [#129](https://github.com/bottrall/acp-sdk/issues/129)
+* read mcpCapabilities alone when deciding whether MCP is advertised ([#139](https://github.com/bottrall/acp-sdk/issues/139)) ([a6e882e](https://github.com/bottrall/acp-sdk/commit/a6e882ebf3c69f0aa8692100e81e61a085007a8b)), closes [#128](https://github.com/bottrall/acp-sdk/issues/128)
+* return a null or false result instead of "Connection closed" ([#137](https://github.com/bottrall/acp-sdk/issues/137)) ([19be64d](https://github.com/bottrall/acp-sdk/commit/19be64df6064e370bb23614a3b8df1056649cd3b)), closes [#127](https://github.com/bottrall/acp-sdk/issues/127)
+* settle a pending request when its response is malformed ([#138](https://github.com/bottrall/acp-sdk/issues/138)) ([7d0586e](https://github.com/bottrall/acp-sdk/commit/7d0586e856a54e5779e4d523bd0862ab57f44b10)), closes [#126](https://github.com/bottrall/acp-sdk/issues/126)
+
 ## [0.10.0](https://github.com/bottrall/acp-sdk/compare/v0.9.0...v0.10.0) (2026-10-07)
 
 

data/README.md

@@ -58,14 +58,17 @@ 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
 
-`ACP::ClientConnection` is the other side of the same transport. Each method takes the request's generated `ACP::Types` object and returns its response type or the agent's `ACP::RequestError`. `connect` sends `initialize`, since Ruby reserves that name for the constructor, and `authenticate` and `logout` send their namesake methods. `session_set_mode` sends `session/set_mode`, and `session_set_config_option` sends `session/set_config_option` and returns the session's complete option list, which replaces any state held from an earlier reply. `session_fork` sends `session/fork`; it is unstable, so the request and response types exist only under `ACP::Types::Unstable` and calling it before `require 'acp/types/unstable'` raises `NameError`. `providers_list`, `providers_set` and `providers_disable` send `providers/list`, `providers/set` and `providers/disable` on the same unstable terms. A handler that raises is answered with `-32603` and the message `Internal error`, and the exception is only logged to the transport's logger.
+`ACP::ClientConnection` is the other side of the same transport. Each method takes the request's generated `ACP::Types` object and returns its response type or the agent's `ACP::RequestError`. `connect` sends `initialize`, since Ruby reserves that name for the constructor, and `authenticate` and `logout` send their namesake methods. `set_session_mode` sends `session/set_mode`, and `set_session_config_option` sends `session/set_config_option` and returns the session's complete option list, which replaces any state held from an earlier reply. `fork_session` sends `session/fork`; it is unstable, so the request and response types exist only under `ACP::Types::Unstable` and calling it before `require 'acp/types/unstable'` raises `NameError`. `list_providers`, `set_provider` and `disable_provider` send `providers/list`, `providers/set` and `providers/disable` on the same unstable terms. A handler that raises is answered with `-32603` and the message `Internal error`, and the exception is only logged to the transport's logger.
 
 `ACP::AgentProcess.spawn` starts a command with args, env and cwd, wires its stdio to a new `ACP::ClientConnection` and starts it. The block receives the connection and the process handle (`pid`, plus `stderr` when captured), and the child is terminated — after its stdin is closed, with TERM and then KILL if it will not exit — when the block exits, so a raised block cannot leak the process. Without a block, `spawn` returns the process and calling `terminate` is yours. `stderr` is `:inherit` by default, so the child writes to your stderr; pass `:capture` to collect it on the process instead.
 
@@ -81,9 +84,9 @@ response = ACP::AgentProcess.spawn(
   updates: ->(notification) { show(notification) }
 ) do |connection|
   connection.connect(ACP::Types::InitializeRequest.new(protocol_version: 1))
-  session = connection.session_new(ACP::Types::NewSessionRequest.new(cwd: Dir.pwd, mcp_servers: []))
+  session = connection.new_session(ACP::Types::NewSessionRequest.new(cwd: Dir.pwd, mcp_servers: []))
   prompt = [ACP::Types::ContentBlock::Text.new(text: 'hello')]
-  connection.session_prompt(ACP::Types::PromptRequest.new(session_id: session.session_id, prompt:)) do |update|
+  connection.prompt_session(ACP::Types::PromptRequest.new(session_id: session.session_id, prompt:)) do |update|
     print update.content.text if update.is_a?(ACP::Types::SessionUpdate::AgentMessageChunk)
   end
 end
@@ -104,15 +107,24 @@ connection = ACP::ClientConnection.new(
 )
 ```
 
-- `session_prompt` and `session_load` yield the session's updates on the calling thread as they arrive and return once the agent replies. Updates outside those calls, such as the available commands after `session/new`, go to `updates`, which runs on the reader thread and must return quickly. `session_resume` does not take a block: the agent must not replay history on resume, so unlike `session_load` there is nothing to stream. `session_close` and `session_delete` end the session, discarding it on the agent, and return once the agent replies.
-- `permission` answers `session/request_permission` with an `ACP::Types::RequestPermissionResponse` or an `ACP::RequestError`. It runs on its own thread, so it may block while the user decides, and `session_cancel` can be sent meanwhile.
+- `prompt_session` and `load_session` yield the session's updates on the calling thread as they arrive and return once the agent replies. Updates outside those calls, such as the available commands after `session/new`, go to `updates`, which runs on the reader thread and must return quickly. `resume_session` does not take a block: the agent must not replay history on resume, so unlike `load_session` there is nothing to stream. `close_session` and `delete_session` end the session, discarding it on the agent, and return once the agent replies.
+- `permission` answers `session/request_permission` with an `ACP::Types::RequestPermissionResponse` or an `ACP::RequestError`. It runs on its own thread, so it may block while the user decides, and `cancel_session` can be sent meanwhile.
 - The agent may cancel any outstanding request with `$/cancel_request`: a handler that can end early checks `connection.cancelled?` — close over the connection when constructing it — and returns `ACP::RequestError.request_cancelled`, which is answered as `-32800`. The permission handler still sees the cancel on its own thread. Whatever the handler returns, the transport sends exactly one response.
 - `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`.
 
+## Types
+
+Every ACP request, response and notification is a generated, frozen value class under `ACP::Types` with `from_h` and `to_h`. A few of its names are deliberate enough to deserve a note:
+
+- `CancelRequestNotification` and `CancelNotification` are different methods with different payloads: the former is the params of the JSON-RPC-level `$/cancel_request`, which the transport handles itself, the latter is the params of ACP's `session/cancel`. Both spellings are the schema's, not a typo.
+- The schema names `session/new`, `session/load`, `session/list` and `session/prompt`'s params and result `NewSessionRequest`, `LoadSessionRequest`, `ListSessionsRequest` and `PromptRequest`, so the wire-shaped spellings exist as alias constants: `ACP::Types::SessionNewRequest`, `SessionLoadRequest`, `SessionListRequest`, `SessionListResponse` and `SessionPromptRequest` are the same classes as their targets. Both names are public API and here to stay — use whichever reads better.
+- The schema's pure string enums are generated as constant modules, for building requests and matching responses without string literals: `ACP::Types::ToolKind::EDIT`, `ACP::Types::StopReason::CANCELLED`, `ACP::Types::PlanEntryPriority::HIGH`, `ACP::Types::Role::USER` and the rest. They carry no validation of their own — the generated `from_h` checks incoming values against the schema regardless of how you build outgoing ones.
+
 ## Unstable types
 
 Some protocol features are not part of the spec yet, so their schema lives in a separate unstable file: draft session updates (`plan_update`, `plan_removed`, `notice`, `compaction_update`, `compaction_summary_chunk`, `subagent_update`, `session_message`, `session_message_chunk`), `PromptResponse#usage`, the NE (next edit) and provider methods, and the matching capabilities. They are generated under `ACP::Types::Unstable` and load only when you opt in:
@@ -125,6 +137,8 @@ Until then, referencing `ACP::Types::Unstable` is a `NameError`, and the stable
 
 These types are **unstable**: they are not part of the ACP spec, agents and clients must not rely on the peer supporting them, and any of them may change or disappear between releases without a major version bump. When a stable schema absorbs one of them, the unstable twin goes away and the stable name stays.
 
+The connections route `session/fork`, the provider methods and `mcp/message`, but not every unstable method has routing yet: the NE methods (`nes/start`, `nes/suggest`, `nes/accept`, `nes/reject`, `nes/close`), the document notifications (`document/didOpen` and friends) and the unstable `ClientCapabilities` are generated as public API for callers wiring those methods at the transport level, and may gain connection routing later.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/bottrall/acp-sdk). See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and workflow. Everyone interacting in the project is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/lib/acp/agent_connection/client.rb

@@ -1,20 +1,17 @@
 # frozen_string_literal: true
 
 class ACP::AgentConnection::Client
-  # @rbs @peer: ACP::AgentConnection::_Peer
+  # @rbs @peer: ACP::Transport::_Peer
   # @rbs @mcp_advertised: bool
 
   # @dynamic capabilities, capabilities=
   attr_accessor :capabilities #: ACP::Types::ClientCapabilities?
 
-  # @rbs peer: ACP::AgentConnection::_Peer
+  # @rbs peer: ACP::Transport::_Peer
   # @rbs mcp_advertised: bool
   # @rbs return: void
   def initialize(peer:, mcp_advertised: false)
     @peer = peer
-    # The agent's own initialize advertisement of mcpCapabilities.acp, which
-    # licenses this side's mcp/message sends; the client's advertisement is
-    # the separate capabilities accessor.
     @mcp_advertised = mcp_advertised
     @capabilities = nil
   end
@@ -33,9 +30,6 @@ class ACP::AgentConnection::Client
     update(session_id, ACP::Types::SessionUpdate::AvailableCommandsUpdate.new(available_commands: commands))
   end
 
-  # Blocks the calling thread until the client answers or the connection
-  # closes.
-  #
   # @rbs request: ACP::Types::RequestPermissionRequest
   # @rbs return: ACP::Types::RequestPermissionResponse | ACP::RequestError
   def request_permission(request)
@@ -123,10 +117,6 @@ class ACP::AgentConnection::Client
     @peer.notify('elicitation/complete', notification.to_h)
   end
 
-  # Sends one inner MCP operation to the client's declared ACP MCP server. The
-  # reply's result may be null, and a reply matching neither carrier branch
-  # comes back as the raw hash.
-  #
   # @rbs request: ACP::Types::Unstable::MessageMcpRequest
   # @rbs return: (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
   def mcp_message(request)
@@ -135,9 +125,7 @@ class ACP::AgentConnection::Client
     call('mcp/message', ACP::Types::Unstable::MessageMcpResponse, request)
   end
 
-  # Sends an extension request, keyed by its raw `_`-prefixed wire name, and
-  # returns the client's reply as-is: extension methods have no schema to
-  # parse the result into.
+  # Extension methods have no schema to parse the result into.
   #
   # @rbs method: String
   # @rbs params: untyped
@@ -158,8 +146,8 @@ class ACP::AgentConnection::Client
   private
 
   # @rbs rpc_method: String
-  # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs request: ACP::AgentConnection::_Response
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs request: ACP::Transport::_Response
   # @rbs return: untyped
   def call(rpc_method, type, request)
     result = @peer.request(rpc_method, request.to_h)
@@ -171,8 +159,8 @@ class ACP::AgentConnection::Client
   end
 
   # @rbs rpc_method: String
-  # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs request: ACP::AgentConnection::_Response
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs request: ACP::Transport::_Response
   # @rbs return: untyped
   def terminal_call(rpc_method, type, request)
     return ACP::RequestError.unadvertised('terminal') unless capabilities&.terminal

data/lib/acp/agent_connection/optional_method/spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class ACP::AgentConnection::OptionalMethod::Spec
+  # @dynamic rpc_method
+  attr_reader :rpc_method #: String
+  # @dynamic agent_method
+  attr_reader :agent_method #: Symbol
+  # @dynamic path
+  attr_reader :path #: Array[Symbol]
+
+  # @rbs rpc_method: String
+  # @rbs agent_method: Symbol
+  # @rbs path: Array[Symbol]
+  # @rbs return: void
+  def initialize(rpc_method:, agent_method:, path:)
+    @rpc_method = rpc_method
+    @agent_method = agent_method
+    @path = path.freeze
+    freeze
+  end
+
+  # Readers missing along the chain count as unadvertised, so the stable
+  # capabilities answer false for the unstable-only paths (fork, providers).
+  #
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?(initialize_response)
+    # reduce's U pins to the InitializeResponse argument, but the chain walks
+    # through unrelated capability types.
+    value = path.reduce(initialize_response) { |node, name| follow(node, name) } #: untyped
+    value ? true : false
+  end
+
+  private
+
+  # @rbs node: untyped
+  # @rbs name: Symbol
+  # @rbs return: untyped
+  def follow(node, name)
+    node.respond_to?(name) ? node.public_send(name) : nil
+  end
+end

data/lib/acp/agent_connection/optional_method.rb

@@ -1,4 +1,40 @@
 # frozen_string_literal: true
 
 module ACP::AgentConnection::OptionalMethod
+  SPECS = [
+    Spec.new(rpc_method: 'authenticate', agent_method: :authenticate, path: %i[auth_methods any?]),
+    Spec.new(rpc_method: 'session/load', agent_method: :load_session, path: %i[agent_capabilities load_session]),
+    Spec.new(
+      rpc_method: 'session/list',
+      agent_method: :list_sessions,
+      path: %i[agent_capabilities session_capabilities list]
+    ),
+    Spec.new(
+      rpc_method: 'session/resume',
+      agent_method: :resume_session,
+      path: %i[agent_capabilities session_capabilities resume]
+    ),
+    Spec.new(
+      rpc_method: 'session/close',
+      agent_method: :close_session,
+      path: %i[agent_capabilities session_capabilities close]
+    ),
+    Spec.new(
+      rpc_method: 'session/delete',
+      agent_method: :delete_session,
+      path: %i[agent_capabilities session_capabilities delete]
+    ),
+    Spec.new(rpc_method: 'logout', agent_method: :logout, path: %i[agent_capabilities auth logout])
+  ].freeze #: Array[Spec]
+
+  UNSTABLE_SPECS = [
+    Spec.new(
+      rpc_method: 'session/fork',
+      agent_method: :fork_session,
+      path: %i[agent_capabilities session_capabilities fork]
+    ),
+    Spec.new(rpc_method: 'providers/list', agent_method: :list_providers, path: %i[agent_capabilities providers]),
+    Spec.new(rpc_method: 'providers/set', agent_method: :set_provider, path: %i[agent_capabilities providers]),
+    Spec.new(rpc_method: 'providers/disable', agent_method: :disable_provider, path: %i[agent_capabilities providers])
+  ].freeze #: Array[Spec]
 end

data/lib/acp/agent_connection.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class ACP::AgentConnection
-  # @rbs @transport: ACP::AgentConnection::_Transport
+  # @rbs @transport: ACP::Transport::_Transport
   # @rbs @capabilities: ACP::Types::AgentCapabilities
   # @rbs @agent_info: ACP::Types::Implementation?
   # @rbs @auth_methods: Array[ACP::Types::AuthMethod::t]
@@ -10,16 +10,6 @@ class ACP::AgentConnection
   # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
   # @rbs @logger: ACP::Transport::_Logger
 
-  PROTOCOL_VERSION = 1 #: Integer
-  OPTIONAL = [
-    ACP::AgentConnection::OptionalMethod::LoadSession,
-    ACP::AgentConnection::OptionalMethod::ListSessions,
-    ACP::AgentConnection::OptionalMethod::Authenticate,
-    ACP::AgentConnection::OptionalMethod::ResumeSession,
-    ACP::AgentConnection::OptionalMethod::CloseSession,
-    ACP::AgentConnection::OptionalMethod::DeleteSession,
-    ACP::AgentConnection::OptionalMethod::Logout
-  ].freeze #: Array[ACP::AgentConnection::_OptionalMethod]
   # The schema has no initialize capability for modes or config options: an
   # agent offers them per session, in its session responses, so they are
   # routed whenever the agent defines them.
@@ -28,7 +18,7 @@ class ACP::AgentConnection
     'session/set_config_option' => :change_session_config_option
   }.freeze #: Hash[String, Symbol]
 
-  # @rbs transport: ACP::AgentConnection::_Transport
+  # @rbs transport: ACP::Transport::_Transport
   # @rbs capabilities: ACP::Types::AgentCapabilities
   # @rbs agent_info: ACP::Types::Implementation?
   # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
@@ -87,7 +77,7 @@ class ACP::AgentConnection
 
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs client: ACP::AgentConnection::Client
-  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)]
   def requests(agent, client)
     # Safe: start drops the optional handlers initialize does not advertise
     # or the agent does not define, and checks the agent defines the rest.
@@ -115,9 +105,9 @@ class ACP::AgentConnection
   # advertises fork or providers.
   #
   # @rbs full: ACP::AgentConnection::_FullAgent
-  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)]
   def unstable_requests(full)
-    return {} unless defined?(ACP::Types::Unstable)
+    return {} unless ACP::Types.unstable_enabled?
 
     {
       'session/fork' => route(ACP::Types::Unstable::ForkSessionRequest) { |request| full.fork_session(request) },
@@ -127,20 +117,16 @@ class ACP::AgentConnection
     }
   end
 
-  # ForkSession's and the provider methods' advertised? reference the unstable
-  # types, so they can only be probed when the caller opted in with
-  # `require 'acp/types/unstable'`.
+  # The unstable specs pair with the unstable request routes, which reference
+  # the unstable request classes, so both are only probed after the caller
+  # opted in with `require 'acp/types/unstable'`.
   #
-  # @rbs return: Array[ACP::AgentConnection::_OptionalMethod]
+  # @rbs return: Array[ACP::AgentConnection::OptionalMethod::Spec]
   def optional_methods
-    return OPTIONAL unless defined?(ACP::Types::Unstable)
+    specs = ACP::AgentConnection::OptionalMethod::SPECS
+    return specs unless ACP::Types.unstable_enabled?
 
-    OPTIONAL + [
-      ACP::AgentConnection::OptionalMethod::ForkSession,
-      ACP::AgentConnection::OptionalMethod::ListProviders,
-      ACP::AgentConnection::OptionalMethod::SetProvider,
-      ACP::AgentConnection::OptionalMethod::DisableProvider
-    ]
+    specs + ACP::AgentConnection::OptionalMethod::UNSTABLE_SPECS
   end
 
   # @rbs agent: ACP::AgentConnection::_Agent
@@ -165,18 +151,9 @@ class ACP::AgentConnection
     agent.cancel(notification)
   end
 
-  # The unstable gates reference the unstable types, so they can only be
-  # probed when the caller opted in with `require 'acp/types/unstable'`; the
-  # stable McpCapabilities has no acp field at all.
-  #
   # @rbs return: bool
   def mcp_acp_advertised?
-    return false unless defined?(ACP::Types::Unstable)
-
-    mcp = @capabilities.mcp_capabilities #: ACP::Types::McpCapabilities | ACP::Types::Unstable::McpCapabilities?
-    return false unless mcp.is_a?(ACP::Types::Unstable::McpCapabilities)
-
-    mcp.acp ? true : false
+    ACP::Protocol.mcp_acp_advertised?(@capabilities)
   end
 
   # A notification has no reply to carry a parse failure.
@@ -195,9 +172,9 @@ class ACP::AgentConnection
 
   # Generated from_h raises on a missing key or a value of the wrong shape.
   #
-  # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs &handle: (untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
-  # @rbs return: ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs &handle: (untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs return: ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
   def route(type, &)
     lambda do |params|
       request = type.from_h(params)
@@ -223,7 +200,7 @@ class ACP::AgentConnection
   # @rbs return: ACP::Types::InitializeResponse
   def initialize_response(auth_methods)
     ACP::Types::InitializeResponse.new(
-      protocol_version: PROTOCOL_VERSION,
+      protocol_version: ACP::Protocol::PROTOCOL_VERSION,
       agent_capabilities: @capabilities,
       auth_methods:,
       agent_info: @agent_info

data/lib/acp/agent_process.rb

@@ -2,8 +2,6 @@
 
 require 'open3'
 
-# A child agent process and the ACP::ClientConnection wired to its stdio.
-# Spawn one with ACP::AgentProcess.spawn.
 class ACP::AgentProcess
   # @rbs @connection: ACP::ClientConnection
   # @rbs @reader: Thread
@@ -21,16 +19,9 @@ class ACP::AgentProcess
   # @dynamic connection
   attr_reader :connection #: ACP::ClientConnection
 
-  # Child stderr captured when spawn was given stderr: :capture, else nil.
-  #
   # @dynamic stderr
   attr_reader :stderr #: String?
 
-  # Starts a command with args, env and cwd, wires its stdio to a new
-  # ACP::ClientConnection and starts it. With a block, yields the connection
-  # and this process, then terminates the child when the block exits; without
-  # one, returns the process and terminate is the caller's job.
-  #
   # @rbs command: String
   # @rbs *args: String
   # @rbs env: Hash[String, String]?
@@ -72,10 +63,6 @@ class ACP::AgentProcess
     end
   end
 
-  # Closes stdin, waits for the child to exit — sending TERM and then KILL if
-  # it will not — and joins the transport reader before closing the pipe it
-  # reads.
-  #
   # @rbs return: void
   def terminate
     @stdin.close unless @stdin.closed?

data/lib/acp/client_connection/streams.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+# It holds no send facade of its own — requests go through the sender and
+# answers to the agent ride the connection's routes — so it is unit-testable
+# without a transport.
+class ACP::ClientConnection::Streams
+  CANCELLED = ACP::Types::RequestPermissionResponse.new(
+    outcome: ACP::Types::RequestPermissionOutcome::Cancelled.new
+  ) #: ACP::Types::RequestPermissionResponse
+
+  # @rbs @sender: ACP::ClientConnection::Streams::_Sender
+  # @rbs @permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs @updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs @complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
+  # @rbs @logger: ACP::Transport::_Logger
+  # @rbs @lock: Thread::Mutex
+  # @rbs @streams: Hash[String, Thread::Queue]
+  # @rbs @pending_permissions: Hash[String, Array[Thread::Queue]]
+  # @rbs @outstanding_elicitations: Hash[String, bool]
+
+  # @rbs sender: ACP::ClientConnection::Streams::_Sender
+  # @rbs permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs logger: ACP::Transport::_Logger
+  # @rbs complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
+  # @rbs return: void
+  def initialize(sender:, permission:, updates:, logger:, complete_elicitation: nil)
+    @sender = sender
+    @permission = permission
+    @updates = updates
+    @complete_elicitation = complete_elicitation
+    @logger = logger
+    @lock = Mutex.new
+    @streams = {}
+    @pending_permissions = {}
+    @outstanding_elicitations = {}
+  end
+
+  # The request waits on its own thread so the caller's thread can yield each
+  # update as it arrives. The reader thread queues an update before it settles
+  # a reply sent after it, so the queue closes only after the last one.
+  #
+  # @rbs session_id: String
+  # @rbs method: String
+  # @rbs params: Hash[String, untyped]
+  # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  def stream(session_id, method, params, &)
+    queue = Thread::Queue.new
+    # The check and the insert share one lock acquisition so a concurrent
+    # stream cannot register between them.
+    claimed = @lock.synchronize do
+      if @streams.key?(session_id)
+        false
+      else
+        @streams[session_id] = queue
+        true
+      end
+    end
+    unless claimed
+      return ACP::RequestError.new(
+        code: ACP::RequestError::INVALID_REQUEST, message: "A stream is already open for session #{session_id}"
+      )
+    end
+    requester = Thread.new do
+      @sender.request(method, params)
+    ensure
+      @lock.synchronize { @streams.delete(session_id)&.close }
+    end
+    while (update = queue.pop)
+      yield update
+    end
+    requester.value
+  end
+
+  # Pushes under the lock so a stream cannot close its queue between the
+  # lookup and the push. A malformed notification has no reply to carry the
+  # failure.
+  #
+  # @rbs params: untyped
+  # @rbs return: void
+  def dispatch(params)
+    notification = ACP::Types::SessionNotification.from_h(params)
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
+    @logger.warn("dropped malformed session/update: #{e.class}: #{e.message}")
+  else
+    queue = @lock.synchronize { @streams[notification.session_id]&.push(notification.update) }
+    @updates.call(notification) unless queue
+  end
+
+  # The handler runs on its own thread so a cancelled request is answered
+  # without waiting for it, and whatever it returns after that is pushed to a
+  # queue nobody reads.
+  #
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
+  def request_permission(params)
+    request = ACP::Types::RequestPermissionRequest.from_h(params)
+  rescue ACP::Types::ParseError => e
+    ACP::RequestError.invalid_params([e.message])
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_params
+  else
+    replies = Thread::Queue.new
+    register_permission(request.session_id, replies)
+    # The handler runs on the transport's serve thread, so the serving
+    # identity must be carried over for cancelled? to see the cancel there.
+    serving = @sender.cancellation
+    Thread.new do
+      ACP::Transport::Cancellation.current = serving
+      # A raised StandardError is not a returned ACP::RequestError, so the two
+      # need distinct shapes on the queue.
+      replies << begin
+        [:value, @permission.call(request)]
+      rescue StandardError => e
+        [:raised, e]
+      end
+    ensure
+      unregister_permission(request.session_id, replies)
+    end
+    settled = replies.pop
+    # Re-raised so the transport's invoke turns it into an error reply, as it
+    # would if the handler ran on the serve thread itself.
+    raise settled[1] if settled[0] == :raised
+
+    settled[1]
+  end
+
+  # The spec requires a pending session/request_permission to be answered with
+  # the cancelled outcome once the turn is cancelled, so every queue registered
+  # for the session gets one before this returns.
+  #
+  # @rbs session_id: String
+  # @rbs return: void
+  def cancel(session_id)
+    pending = @lock.synchronize { @pending_permissions.delete(session_id) }
+    pending&.each { |replies| replies << [:value, CANCELLED] }
+  end
+
+  # @rbs elicitation_id: String
+  # @rbs return: void
+  def register_elicitation(elicitation_id)
+    @lock.synchronize { @outstanding_elicitations[elicitation_id] = true }
+  end
+
+  # The spec requires a completion for an unknown or already-completed
+  # elicitation id to be ignored, so only an id registered by a served
+  # url-mode request reaches the handler. It runs on the transport's reader
+  # thread, so it must return quickly.
+  #
+  # @rbs params: untyped
+  # @rbs return: void
+  def complete_elicitation(params)
+    notification = ACP::Types::CompleteElicitationNotification.from_h(params)
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
+    @logger.warn("dropped malformed elicitation/complete: #{e.class}: #{e.message}")
+  else
+    known = @lock.synchronize { @outstanding_elicitations.delete(notification.elicitation_id) }
+    @complete_elicitation&.call(notification) if known
+  end
+
+  private
+
+  # @rbs session_id: String
+  # @rbs replies: Thread::Queue
+  # @rbs return: void
+  def register_permission(session_id, replies)
+    @lock.synchronize { (@pending_permissions[session_id] ||= []) << replies }
+  end
+
+  # @rbs session_id: String
+  # @rbs replies: Thread::Queue
+  # @rbs return: void
+  def unregister_permission(session_id, replies)
+    @lock.synchronize do
+      pending = @pending_permissions[session_id]
+      if pending
+        pending.delete(replies)
+        @pending_permissions.delete(session_id) if pending.empty?
+      end
+    end
+  end
+end