acp-sdk 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8a4bb93508ff8a9737b9b5b044e4b63e19ba87393490f10f522b9b63aee4396
-  data.tar.gz: 9e62dd726471fd718c2a234b9ea65bc90ca473c67d979e207b2702edd33b30b5
+  metadata.gz: e0d983006184ce11ac51e9361062aa6878c01d348645f41fe226423db5d72e8b
+  data.tar.gz: 0d50ff69cb0c6cc743d75dcd3fd943a9ddeaa4469a8f1e8d6e54be811e3c3b39
 SHA512:
-  metadata.gz: 50ef3954c1104ef512b757421bb0df10d3eb0be7f245c5a26c8641e815fa54d160a1d4d2c8369b9b41eb4b64affce206c584627650a5ce3446be09f88f2239b4
-  data.tar.gz: 0e505cd00fd0fef743dc1c047892db07b1ea4bf0999b3c0bff402fc10f73609a23fcbd4310b4a8deb7822fd06d8a64d1bab517426302004c205b3eee2972a104
+  metadata.gz: 4296fbbf1fa985cb3913f2019528c06658fd8fcac285a238abf79073d2d5eb13d081e69da57f05476569967189f732c804f6dc851e291709c0b4052572b17d9f
+  data.tar.gz: 8f0a5bedfa32615f867111297c4fc593f2b567fd77a55e76dda4eabe57bd8494e225de93b470f1ac294f4b99a57797fda4d7f69704693fb8cd322e65fe650f59

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.10.0](https://github.com/bottrall/acp-sdk/compare/v0.9.0...v0.10.0) (2026-10-07)
+
+
+### Features
+
+* MCP-over-ACP mcp/message (unstable) ([#89](https://github.com/bottrall/acp-sdk/issues/89)) ([3d6d30c](https://github.com/bottrall/acp-sdk/commit/3d6d30c6e31e88dd0fe78e08a5bc4308948cacdd))
+* providers/list, providers/set and providers/disable (unstable) ([#88](https://github.com/bottrall/acp-sdk/issues/88)) ([eac16f7](https://github.com/bottrall/acp-sdk/commit/eac16f78809ea5a677835c6fe064063dcb64c162)), closes [#50](https://github.com/bottrall/acp-sdk/issues/50)
+* request cancellation on the agent and client connections ([#85](https://github.com/bottrall/acp-sdk/issues/85)) ([58ae0ab](https://github.com/bottrall/acp-sdk/commit/58ae0abe6387e2887482ec14e361cfac91cd54ea))
+* session/fork (unstable) ([#86](https://github.com/bottrall/acp-sdk/issues/86)) ([9868cb6](https://github.com/bottrall/acp-sdk/commit/9868cb666a8111c414bf3b041167d6aa022e1e95)), closes [#49](https://github.com/bottrall/acp-sdk/issues/49)
+* support all currently supported Ruby versions ([#90](https://github.com/bottrall/acp-sdk/issues/90)) ([343d07b](https://github.com/bottrall/acp-sdk/commit/343d07b9e6d98b1c24201c5eef8b250858c0626b)), closes [#73](https://github.com/bottrall/acp-sdk/issues/73)
+
 ## [0.9.0](https://github.com/bottrall/acp-sdk/compare/v0.8.0...v0.9.0) (2026-10-07)
 
 

data/README.md

@@ -11,7 +11,7 @@ Every ACP request, response and notification is a generated Ruby class under `AC
 
 ## Installation
 
-Requires Ruby 4.0 or later.
+Requires Ruby 3.4 or later (CI tests 3.4 and 4.0).
 
 Add the gem to your Gemfile:
 
@@ -48,11 +48,12 @@ connection.start.join
 
 The agent's contract:
 
-- It defines `new_session`, `prompt` and `cancel`. `load_session`, `list_sessions`, `resume_session`, `close_session` and `delete_session` are required only when `capabilities` advertises `load_session` or `session_capabilities.list`, `.resume`, `.close` or `.delete`, and `authenticate` only when `auth_methods` is non-empty, and `logout` only when `capabilities` advertises `auth.logout`; `start` raises `ArgumentError` when one is advertised but missing, and a method that is not advertised is answered with `-32601`. `change_session_mode` and `change_session_config_option` are optional, since modes and config options are offered per session rather than in `initialize`; `session/set_mode` and `session/set_config_option` are answered with `-32601` when the agent does not define them. `session_created`, if defined, runs right after the `session/new` reply is sent.
+- It defines `new_session`, `prompt` and `cancel`. `load_session`, `list_sessions`, `resume_session`, `close_session` and `delete_session` are required only when `capabilities` advertises `load_session` or `session_capabilities.list`, `.resume`, `.close` or `.delete`, and `authenticate` only when `auth_methods` is non-empty, and `logout` only when `capabilities` advertises `auth.logout`; `start` raises `ArgumentError` when one is advertised but missing, and a method that is not advertised is answered with `-32601`. `change_session_mode` and `change_session_config_option` are optional, since modes and config options are offered per session rather than in `initialize`; `session/set_mode` and `session/set_config_option` are answered with `-32601` when the agent does not define them. `session_created`, if defined, runs right after the `session/new` reply is sent. `fork_session` is the same shape but unstable: `session/fork` routes only when the caller has opted into the unstable types with `require 'acp/types/unstable'` and `capabilities` advertises `session_capabilities.fork`, and is answered with `-32601` otherwise. `list_providers`, `set_provider` and `disable_provider` are the same shape but unstable too: `providers/list`, `providers/set` and `providers/disable` route only when the caller has opted into the unstable types with `require 'acp/types/unstable'` and `capabilities` advertises `providers`, and are answered with `-32601` otherwise.
 - Each request method returns its response type or an `ACP::RequestError`, which is sent as the error reply. Params that do not match the schema are answered with `-32602` before the agent sees them, with `data` naming the failing path, e.g. `{ errors: ['sessionId: expected String, got Integer'] }`.
 - A handler that raises is answered with `-32603` and the message `Internal error`. Nothing from the exception reaches the peer — its class and message are logged to the transport's logger instead, since messages can interpolate paths, queries or credentials. Return an `ACP::RequestError` from the handler when the peer should see a real error message.
-- `cancel` runs on the transport's reader thread, so it must return quickly: set a flag and let the prompt notice it.
+- `cancel` runs on the transport's reader thread, so it must return quickly: set a flag and let the prompt notice it, and call `client.cancel_requests` to cancel the connection's outstanding requests to the client — a blocked `request_permission` or `wait_for_terminal_exit`, say. That sends `$/cancel_request` for each one, and the blocked call returns once the client answers it, with its response or the `-32800` error.
 - After a cancel, the agent must itself end the turn with `stopReason: cancelled`. `ACP::AgentConnection` does not enforce it.
+- `client.cancelled?` is true in a handler when the client cancelled the request it is serving with `$/cancel_request`. The handler can end early by returning `ACP::RequestError.request_cancelled`, which is answered as `-32800`, or return a normal response, which is sent as-is — the transport sends exactly one response either way.
 - `client.capabilities` is `nil` until the client sends `initialize`.
 - `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.
@@ -64,7 +65,7 @@ Extensions are `_`-prefixed methods outside the spec. `AgentConnection` takes `e
 
 ## 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. 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. `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::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.
 
@@ -105,6 +106,7 @@ 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.
+- 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.

data/lib/acp/agent_connection/client.rb

@@ -2,14 +2,20 @@
 
 class ACP::AgentConnection::Client
   # @rbs @peer: ACP::AgentConnection::_Peer
+  # @rbs @mcp_advertised: bool
 
   # @dynamic capabilities, capabilities=
   attr_accessor :capabilities #: ACP::Types::ClientCapabilities?
 
   # @rbs peer: ACP::AgentConnection::_Peer
+  # @rbs mcp_advertised: bool
   # @rbs return: void
-  def initialize(peer:)
+  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
 
@@ -36,6 +42,18 @@ class ACP::AgentConnection::Client
     call('session/request_permission', ACP::Types::RequestPermissionResponse, request)
   end
 
+  # @rbs return: void
+  def cancel_requests
+    @peer.cancel_requests
+  end
+
+  # Always false off a handler thread.
+  #
+  # @rbs return: bool
+  def cancelled?
+    !!@peer.cancellation&.cancelled?
+  end
+
   # @rbs request: ACP::Types::ReadTextFileRequest
   # @rbs return: ACP::Types::ReadTextFileResponse | ACP::RequestError
   def read_text_file(request)
@@ -105,6 +123,18 @@ 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)
+    return ACP::RequestError.unadvertised_agent('mcpCapabilities.acp') unless @mcp_advertised
+
+    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.

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ACP::AgentConnection::OptionalMethod::DisableProvider
+  extend self
+
+  # @rbs return: String
+  def rpc_method
+    'providers/disable'
+  end
+
+  # @rbs return: Symbol
+  def agent_method
+    :disable_provider
+  end
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?(initialize_response)
+    capabilities = initialize_response.agent_capabilities #: ACP::Types::AgentCapabilities | ACP::Types::Unstable::AgentCapabilities?
+    providers = capabilities.is_a?(ACP::Types::Unstable::AgentCapabilities) ? capabilities.providers : nil #: ACP::Types::Unstable::ProvidersCapabilities?
+    providers ? true : false
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ACP::AgentConnection::OptionalMethod::ForkSession
+  extend self
+
+  # @rbs return: String
+  def rpc_method
+    'session/fork'
+  end
+
+  # @rbs return: Symbol
+  def agent_method
+    :fork_session
+  end
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?(initialize_response)
+    session = initialize_response.agent_capabilities&.session_capabilities #: ACP::Types::SessionCapabilities | ACP::Types::Unstable::SessionCapabilities?
+    fork = session.is_a?(ACP::Types::Unstable::SessionCapabilities) ? session.fork : nil #: ACP::Types::Unstable::SessionForkCapabilities?
+    fork ? true : false
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ACP::AgentConnection::OptionalMethod::ListProviders
+  extend self
+
+  # @rbs return: String
+  def rpc_method
+    'providers/list'
+  end
+
+  # @rbs return: Symbol
+  def agent_method
+    :list_providers
+  end
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?(initialize_response)
+    capabilities = initialize_response.agent_capabilities #: ACP::Types::AgentCapabilities | ACP::Types::Unstable::AgentCapabilities?
+    providers = capabilities.is_a?(ACP::Types::Unstable::AgentCapabilities) ? capabilities.providers : nil #: ACP::Types::Unstable::ProvidersCapabilities?
+    providers ? true : false
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ACP::AgentConnection::OptionalMethod::SetProvider
+  extend self
+
+  # @rbs return: String
+  def rpc_method
+    'providers/set'
+  end
+
+  # @rbs return: Symbol
+  def agent_method
+    :set_provider
+  end
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?(initialize_response)
+    capabilities = initialize_response.agent_capabilities #: ACP::Types::AgentCapabilities | ACP::Types::Unstable::AgentCapabilities?
+    providers = capabilities.is_a?(ACP::Types::Unstable::AgentCapabilities) ? capabilities.providers : nil #: ACP::Types::Unstable::ProvidersCapabilities?
+    providers ? true : false
+  end
+end

data/lib/acp/agent_connection.rb

@@ -61,15 +61,21 @@ class ACP::AgentConnection
 
   # @rbs return: Thread
   def start
-    client = ACP::AgentConnection::Client.new(peer: @transport)
+    client = ACP::AgentConnection::Client.new(peer: @transport, mcp_advertised: mcp_acp_advertised?)
     agent = @factory.call(client)
     # Routes are fixed before a client connects, so the check sees the
     # unfiltered auth methods: a terminal-capable client still needs
     # authenticate routed.
-    advertised, unadvertised = OPTIONAL.partition { |method| method.advertised?(initialize_response(@auth_methods)) }
+    advertised, unadvertised = optional_methods.partition do |method|
+      method.advertised?(initialize_response(@auth_methods))
+    end
     missing = advertised.map(&:agent_method).reject { |name| agent.respond_to?(name) }
     raise ArgumentError, "initialize advertises methods the agent lacks: #{missing.join(', ')}" unless missing.empty?
 
+    if mcp_acp_advertised? && !agent.respond_to?(:mcp_message_notification)
+      raise ArgumentError, 'initialize advertises mcpCapabilities.acp but the agent lacks mcp_message_notification'
+    end
+
     unrouted = unadvertised.map(&:rpc_method) + PER_SESSION.reject { |_, name| agent.respond_to?(name) }.keys
     @transport.start(
       requests: requests(agent, client).except(*unrouted).merge(@extension_requests),
@@ -101,13 +107,49 @@ class ACP::AgentConnection
       'session/set_config_option' => route(ACP::Types::SetSessionConfigOptionRequest) do |request|
         full.change_session_config_option(request)
       end
+    }.merge(unstable_requests(full))
+  end
+
+  # The unstable request types are referenced while the hash is built, so
+  # without the guard start would raise NameError even for an agent that never
+  # advertises fork or providers.
+  #
+  # @rbs full: ACP::AgentConnection::_FullAgent
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  def unstable_requests(full)
+    return {} unless defined?(ACP::Types::Unstable)
+
+    {
+      'session/fork' => route(ACP::Types::Unstable::ForkSessionRequest) { |request| full.fork_session(request) },
+      'providers/list' => route(ACP::Types::Unstable::ListProvidersRequest) { |request| full.list_providers(request) },
+      'providers/set' => route(ACP::Types::Unstable::SetProviderRequest) { |request| full.set_provider(request) },
+      'providers/disable' => route(ACP::Types::Unstable::DisableProviderRequest) { |request| full.disable_provider(request) }
     }
   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'`.
+  #
+  # @rbs return: Array[ACP::AgentConnection::_OptionalMethod]
+  def optional_methods
+    return OPTIONAL unless defined?(ACP::Types::Unstable)
+
+    OPTIONAL + [
+      ACP::AgentConnection::OptionalMethod::ForkSession,
+      ACP::AgentConnection::OptionalMethod::ListProviders,
+      ACP::AgentConnection::OptionalMethod::SetProvider,
+      ACP::AgentConnection::OptionalMethod::DisableProvider
+    ]
+  end
+
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs return: Hash[String, ^(untyped) -> void]
   def notifications(agent)
-    { 'session/cancel' => ->(params) { cancel(agent, params) } }
+    routes = { 'session/cancel' => ->(params) { cancel(agent, params) } }
+    return routes unless mcp_acp_advertised?
+
+    routes.merge('mcp/message' => ->(params) { mcp_message_notification(agent, params) })
   end
 
   # A notification has no reply to carry a parse failure.
@@ -123,6 +165,34 @@ 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
+  end
+
+  # A notification has no reply to carry a parse failure.
+  #
+  # @rbs agent: ACP::AgentConnection::_Agent
+  # @rbs params: untyped
+  # @rbs return: void
+  def mcp_message_notification(agent, params)
+    notification = ACP::Types::Unstable::MessageMcpNotification.from_h(params)
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
+    @logger.warn("dropped malformed mcp/message: #{e.class}: #{e.message}")
+  else
+    hook = agent #: ACP::AgentConnection::_Agent & ACP::AgentConnection::_McpMessageNotification
+    hook.mcp_message_notification(notification)
+  end
+
   # Generated from_h raises on a missing key or a value of the wrong shape.
   #
   # @rbs type: ACP::AgentConnection::_Parser

data/lib/acp/client_connection.rb

@@ -15,6 +15,9 @@ class ACP::ClientConnection
   #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
   # @rbs @complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs @updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs @mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) ->
+  #   (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
+  # @rbs @mcp_advertised: bool?
   # @rbs @fs_capabilities: ACP::Types::FileSystemCapabilities?
   # @rbs @terminal: bool?
   # @rbs @elicitation_capabilities: ACP::Types::ElicitationCapabilities?
@@ -48,6 +51,8 @@ class ACP::ClientConnection
   #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
   # @rbs complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) ->
+  #   (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
   # @rbs extension_requests: Hash[String, ^(untyped) -> untyped]
   # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
   # @rbs logger: ACP::Transport::_Logger
@@ -65,6 +70,7 @@ class ACP::ClientConnection
     elicitation: nil,
     complete_elicitation: nil,
     updates: IGNORE,
+    mcp_message: nil,
     extension_requests: {},
     extension_notifications: {},
     logger: ACP::Transport::StderrLogger.new
@@ -81,6 +87,8 @@ class ACP::ClientConnection
     @elicitation = elicitation
     @complete_elicitation = complete_elicitation
     @updates = updates
+    @mcp_message = mcp_message
+    @mcp_advertised = nil
     @fs_capabilities = nil
     @terminal = nil
     @elicitation_capabilities = nil
@@ -108,7 +116,7 @@ class ACP::ClientConnection
         'terminal/kill' => method(:kill_terminal),
         'terminal/release' => method(:release_terminal),
         'elicitation/create' => method(:create_elicitation)
-      }.merge(@extension_requests),
+      }.merge(mcp_requests).merge(@extension_requests),
       notifications: { 'session/update' => method(:dispatch),
                        'elicitation/complete' => method(:complete_elicitation) }.merge(@extension_notifications)
     )
@@ -141,16 +149,17 @@ class ACP::ClientConnection
     @fs_capabilities = capabilities
     @terminal = terminal
     @elicitation_capabilities = elicitation
-    parse(ACP::Types::InitializeResponse, @transport.request('initialize', request.to_h)).then do |response|
-      next response if response.is_a?(ACP::RequestError)
+    result = @transport.request('initialize', request.to_h)
+    response = parse(ACP::Types::InitializeResponse, result)
+    return response if response.is_a?(ACP::RequestError)
 
-      next response if response.protocol_version == PROTOCOL_VERSION
+    @mcp_advertised = agent_mcp_advertised?(result)
+    return response if response.protocol_version == PROTOCOL_VERSION
 
-      ACP::RequestError.unsupported_protocol_version(
-        requested: request.protocol_version,
-        returned: response.protocol_version
-      )
-    end
+    ACP::RequestError.unsupported_protocol_version(
+      requested: request.protocol_version,
+      returned: response.protocol_version
+    )
   end
 
   # @rbs request: ACP::Types::NewSessionRequest
@@ -200,6 +209,30 @@ class ACP::ClientConnection
     parse(ACP::Types::DeleteSessionResponse, @transport.request('session/delete', request.to_h))
   end
 
+  # @rbs request: ACP::Types::Unstable::ForkSessionRequest
+  # @rbs return: (ACP::Types::Unstable::ForkSessionResponse | ACP::RequestError)
+  def session_fork(request)
+    parse(ACP::Types::Unstable::ForkSessionResponse, @transport.request('session/fork', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::Unstable::ListProvidersRequest
+  # @rbs return: (ACP::Types::Unstable::ListProvidersResponse | ACP::RequestError)
+  def providers_list(request)
+    parse(ACP::Types::Unstable::ListProvidersResponse, @transport.request('providers/list', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::Unstable::SetProviderRequest
+  # @rbs return: (ACP::Types::Unstable::SetProviderResponse | ACP::RequestError)
+  def providers_set(request)
+    parse(ACP::Types::Unstable::SetProviderResponse, @transport.request('providers/set', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::Unstable::DisableProviderRequest
+  # @rbs return: (ACP::Types::Unstable::DisableProviderResponse | ACP::RequestError)
+  def providers_disable(request)
+    parse(ACP::Types::Unstable::DisableProviderResponse, @transport.request('providers/disable', request.to_h))
+  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. The notification goes first
@@ -252,6 +285,13 @@ class ACP::ClientConnection
     @transport.request(method, params)
   end
 
+  # Always false off a handler thread.
+  #
+  # @rbs return: bool
+  def cancelled?
+    !!@transport.cancellation&.cancelled?
+  end
+
   # @rbs method: String
   # @rbs params: untyped
   # @rbs return: void
@@ -260,8 +300,44 @@ class ACP::ClientConnection
     @transport.notify(method, params)
   end
 
+  # Unlike the mcp/message serve route, this send is not gated: a notification
+  # has no reply to carry a refusal, and the agent drops what it did not
+  # advertise.
+  #
+  # @rbs notification: ACP::Types::Unstable::MessageMcpNotification
+  # @rbs return: void
+  def mcp_message_notification(notification)
+    @transport.notify('mcp/message', notification.to_h)
+  end
+
   private
 
+  # The route is only registered when a handler serves it, but the agent's
+  # advertisement is only known after connect, so an unadvertised request
+  # still reaches the route and is refused there.
+  #
+  # @rbs return: Hash[String, ACP::Transport::Stdio::_Handler]
+  def mcp_requests
+    return {} unless @mcp_message
+
+    { 'mcp/message' => method(:mcp_message) }
+  end
+
+  # The stable McpCapabilities has no acp field, so the gate re-reads the raw
+  # initialize reply with the unstable types when they are opted into.
+  #
+  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
+  # @rbs return: bool
+  def agent_mcp_advertised?(result)
+    return false unless defined?(ACP::Types::Unstable)
+    return false unless result.is_a?(Hash)
+
+    mcp = ACP::Types::Unstable::McpCapabilities.from_h(result['agentCapabilities']['mcpCapabilities'] || {})
+    mcp.acp ? true : false
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError
+    false
+  end
+
   # @rbs type: ACP::AgentConnection::_Parser
   # @rbs result: (Hash[String, untyped] | ACP::RequestError)
   # @rbs return: untyped
@@ -340,7 +416,11 @@ class ACP::ClientConnection
   else
     replies = Thread::Queue.new
     register_permission(request.session_id, replies)
+    # The handler runs on this connection's own thread, so the serving
+    # identity must be carried over for cancelled? to see the cancel there.
+    serving = @transport.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
@@ -490,6 +570,25 @@ class ACP::ClientConnection
     handler.call(request)
   end
 
+  # The route is registered at start, before connect records the agent's
+  # advertisement, so an unadvertised request answers -32601 until then.
+  #
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
+  def mcp_message(params)
+    return ACP::RequestError.unadvertised_agent('mcpCapabilities.acp') unless @mcp_advertised
+
+    request = ACP::Types::Unstable::MessageMcpRequest.from_h(params)
+  rescue ACP::Types::ParseError => e
+    ACP::RequestError.invalid_params([e.message])
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_params
+  else
+    # Safe: the route is only registered when a handler serves it.
+    handler = @mcp_message #: ^(ACP::Types::Unstable::MessageMcpRequest) -> (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
+    handler.call(request)
+  end
+
   # The routes are registered at start, before connect records the advertised
   # capabilities, so a request for an unadvertised mode answers -32602.
   #

data/lib/acp/request_error.rb

@@ -82,6 +82,16 @@ class ACP::RequestError
     new(code: INVALID_PARAMS, message: "Client does not advertise #{mode}")
   end
 
+  # unadvertised names a capability of the client's, this one a capability of
+  # the agent's: the same method-not-found code, with a message naming which
+  # side's advertisement is missing.
+  #
+  # @rbs capability: String
+  # @rbs return: ACP::RequestError
+  def self.unadvertised_agent(capability)
+    new(code: METHOD_NOT_FOUND, message: "Agent does not advertise #{capability}")
+  end
+
   # @rbs return: ACP::RequestError
   def self.internal_error
     new(code: INTERNAL_ERROR, message: 'Internal error')

data/lib/acp/transport/cancellation.rb

@@ -4,6 +4,23 @@
 # request, marks it when the peer's $/cancel_request arrives, and hands it to
 # the serving thread, whose handler can observe it and end the request early.
 class ACP::Transport::Cancellation
+  KEY = :acp_serving_cancellation #: Symbol
+
+  # Connections read this to expose the serving state to their handlers and
+  # write it to carry serving identity onto a thread they spawn; nil off a
+  # serve thread.
+  #
+  # @rbs return: ACP::Transport::Cancellation?
+  def self.current
+    Thread.current[KEY] #: ACP::Transport::Cancellation?
+  end
+
+  # @rbs cancellation: ACP::Transport::Cancellation?
+  # @rbs return: void
+  def self.current=(cancellation)
+    Thread.current[KEY] = cancellation
+  end
+
   # @rbs @lock: Thread::Mutex
   # @rbs @cancelled: bool
 

data/lib/acp/transport/stdio.rb

@@ -22,9 +22,6 @@ class ACP::Transport::Stdio
     code: ACP::RequestError::INTERNAL_ERROR, message: 'Connection closed'
   ) #: ACP::RequestError
 
-  SERVING_CANCEL = :acp_serving_cancellation #: Symbol
-  private_constant :SERVING_CANCEL
-
   # @rbs input: _Reader
   # @rbs output: _Writer
   # @rbs logger: ACP::Transport::_Logger
@@ -85,6 +82,14 @@ class ACP::Transport::Stdio
     notify('$/cancel_request', { 'requestId' => id }) if pending
   end
 
+  # Each id is re-checked against the pending table, so one that settled
+  # between the snapshot and its cancel is not cancelled.
+  #
+  # @rbs return: void
+  def cancel_requests
+    @lock.synchronize { @pending.keys }.each { |id| cancel(id) }
+  end
+
   # The cancellation of the request the calling thread is serving, or nil off
   # a serve thread. A handler observes the peer's $/cancel_request through it
   # and can end early with ACP::RequestError.request_cancelled; whatever it
@@ -92,7 +97,7 @@ class ACP::Transport::Stdio
   #
   # @rbs return: ACP::Transport::Cancellation?
   def cancellation
-    Thread.current[SERVING_CANCEL] #: ACP::Transport::Cancellation?
+    ACP::Transport::Cancellation.current
   end
 
   private
@@ -167,7 +172,7 @@ class ACP::Transport::Stdio
   def serve(handler, id, params, method)
     cancellation = register_serving(id)
     Thread.new do
-      Thread.current[SERVING_CANCEL] = cancellation
+      ACP::Transport::Cancellation.current = cancellation
       outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
       case outcome
       when ACP::Transport::Reply

data/lib/acp/types/unstable/message_mcp_response/result.rb

@@ -27,6 +27,6 @@ class ACP::Types::Unstable::MessageMcpResponse::Result
 
   # @rbs return: Hash[String, untyped]
   def to_h
-    { 'result' => result, '_meta' => meta }.compact
+    { '_meta' => meta }.compact.merge('result' => result)
   end
 end

data/lib/acp/version.rb

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

data/sig/generated/acp/agent_connection/client.rbs

@@ -1,14 +1,17 @@
 # Generated from lib/acp/agent_connection/client.rb with RBS::Inline
 
 class ACP::AgentConnection::Client
+  @mcp_advertised: bool
+
   @peer: ACP::AgentConnection::_Peer
 
   # @dynamic capabilities, capabilities=
   attr_accessor capabilities: ACP::Types::ClientCapabilities?
 
   # @rbs peer: ACP::AgentConnection::_Peer
+  # @rbs mcp_advertised: bool
   # @rbs return: void
-  def initialize: (peer: ACP::AgentConnection::_Peer) -> void
+  def initialize: (peer: ACP::AgentConnection::_Peer, ?mcp_advertised: bool) -> void
 
   # @rbs session_id: String
   # @rbs update: ACP::Types::SessionUpdate::t
@@ -27,6 +30,14 @@ class ACP::AgentConnection::Client
   # @rbs return: ACP::Types::RequestPermissionResponse | ACP::RequestError
   def request_permission: (ACP::Types::RequestPermissionRequest request) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
 
+  # @rbs return: void
+  def cancel_requests: () -> void
+
+  # Always false off a handler thread.
+  #
+  # @rbs return: bool
+  def cancelled?: () -> bool
+
   # @rbs request: ACP::Types::ReadTextFileRequest
   # @rbs return: ACP::Types::ReadTextFileResponse | ACP::RequestError
   def read_text_file: (ACP::Types::ReadTextFileRequest request) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
@@ -63,6 +74,14 @@ class ACP::AgentConnection::Client
   # @rbs return: void
   def complete_elicitation: (ACP::Types::CompleteElicitationNotification notification) -> void
 
+  # 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: (ACP::Types::Unstable::MessageMcpRequest request) -> (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
+
   # 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.

data/sig/generated/acp/agent_connection/optional_method/disable_provider.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/acp/agent_connection/optional_method/disable_provider.rb with RBS::Inline
+
+module ACP::AgentConnection::OptionalMethod::DisableProvider
+  # @rbs return: String
+  def rpc_method: () -> String
+
+  # @rbs return: Symbol
+  def agent_method: () -> Symbol
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?: (ACP::Types::InitializeResponse initialize_response) -> bool
+end

data/sig/generated/acp/agent_connection/optional_method/fork_session.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/acp/agent_connection/optional_method/fork_session.rb with RBS::Inline
+
+module ACP::AgentConnection::OptionalMethod::ForkSession
+  # @rbs return: String
+  def rpc_method: () -> String
+
+  # @rbs return: Symbol
+  def agent_method: () -> Symbol
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?: (ACP::Types::InitializeResponse initialize_response) -> bool
+end

data/sig/generated/acp/agent_connection/optional_method/list_providers.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/acp/agent_connection/optional_method/list_providers.rb with RBS::Inline
+
+module ACP::AgentConnection::OptionalMethod::ListProviders
+  # @rbs return: String
+  def rpc_method: () -> String
+
+  # @rbs return: Symbol
+  def agent_method: () -> Symbol
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?: (ACP::Types::InitializeResponse initialize_response) -> bool
+end

data/sig/generated/acp/agent_connection/optional_method/set_provider.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/acp/agent_connection/optional_method/set_provider.rb with RBS::Inline
+
+module ACP::AgentConnection::OptionalMethod::SetProvider
+  # @rbs return: String
+  def rpc_method: () -> String
+
+  # @rbs return: Symbol
+  def agent_method: () -> Symbol
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?: (ACP::Types::InitializeResponse initialize_response) -> bool
+end

data/sig/generated/acp/agent_connection.rbs

@@ -47,6 +47,21 @@ class ACP::AgentConnection
   # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
   def requests: (ACP::AgentConnection::_Agent agent, ACP::AgentConnection::Client client) -> Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
 
+  # The unstable request types are referenced while the hash is built, so
+  # without the guard start would raise NameError even for an agent that never
+  # advertises fork or providers.
+  #
+  # @rbs full: ACP::AgentConnection::_FullAgent
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  def unstable_requests: (ACP::AgentConnection::_FullAgent full) -> Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+
+  # 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'`.
+  #
+  # @rbs return: Array[ACP::AgentConnection::_OptionalMethod]
+  def optional_methods: () -> Array[ACP::AgentConnection::_OptionalMethod]
+
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs return: Hash[String, ^(untyped) -> void]
   def notifications: (ACP::AgentConnection::_Agent agent) -> Hash[String, ^(untyped) -> void]
@@ -58,6 +73,20 @@ class ACP::AgentConnection
   # @rbs return: void
   def cancel: (ACP::AgentConnection::_Agent agent, untyped params) -> void
 
+  # 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?: () -> bool
+
+  # A notification has no reply to carry a parse failure.
+  #
+  # @rbs agent: ACP::AgentConnection::_Agent
+  # @rbs params: untyped
+  # @rbs return: void
+  def mcp_message_notification: (ACP::AgentConnection::_Agent agent, untyped params) -> void
+
   # Generated from_h raises on a missing key or a value of the wrong shape.
   #
   # @rbs type: ACP::AgentConnection::_Parser

data/sig/generated/acp/client_connection.rbs

@@ -25,6 +25,10 @@ class ACP::ClientConnection
 
   @updates: ACP::ClientConnection::_UpdateHandler
 
+  @mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) -> (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
+
+  @mcp_advertised: bool?
+
   @fs_capabilities: ACP::Types::FileSystemCapabilities?
 
   @terminal: bool?
@@ -65,11 +69,13 @@ class ACP::ClientConnection
   #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
   # @rbs complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) ->
+  #   (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
   # @rbs extension_requests: Hash[String, ^(untyped) -> untyped]
   # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
   # @rbs logger: ACP::Transport::_Logger
   # @rbs return: void
-  def initialize: (transport: ACP::AgentConnection::_Transport, permission: ACP::ClientConnection::_PermissionHandler, ?read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?, ?write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?, ?create_terminal: (^(ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError))?, ?terminal_output: (^(ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError))?, ?wait_for_terminal_exit: (^(ACP::Types::WaitForTerminalExitRequest) -> (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError))?, ?kill_terminal: (^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError))?, ?release_terminal: (^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError))?, ?elicitation: (^(ACP::Types::CreateElicitationRequest) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError))?, ?complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?, ?updates: ACP::ClientConnection::_UpdateHandler, ?extension_requests: Hash[String, ^(untyped) -> untyped], ?extension_notifications: Hash[String, ^(untyped) -> void], ?logger: ACP::Transport::_Logger) -> void
+  def initialize: (transport: ACP::AgentConnection::_Transport, permission: ACP::ClientConnection::_PermissionHandler, ?read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?, ?write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?, ?create_terminal: (^(ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError))?, ?terminal_output: (^(ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError))?, ?wait_for_terminal_exit: (^(ACP::Types::WaitForTerminalExitRequest) -> (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError))?, ?kill_terminal: (^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError))?, ?release_terminal: (^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError))?, ?elicitation: (^(ACP::Types::CreateElicitationRequest) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError))?, ?complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?, ?updates: ACP::ClientConnection::_UpdateHandler, ?mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) -> (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?, ?extension_requests: Hash[String, ^(untyped) -> untyped], ?extension_notifications: Hash[String, ^(untyped) -> void], ?logger: ACP::Transport::_Logger) -> void
 
   # @rbs return: Thread
   def start: () -> Thread
@@ -114,6 +120,22 @@ class ACP::ClientConnection
   # @rbs return: ACP::Types::DeleteSessionResponse | ACP::RequestError
   def session_delete: (ACP::Types::DeleteSessionRequest request) -> (ACP::Types::DeleteSessionResponse | ACP::RequestError)
 
+  # @rbs request: ACP::Types::Unstable::ForkSessionRequest
+  # @rbs return: (ACP::Types::Unstable::ForkSessionResponse | ACP::RequestError)
+  def session_fork: (ACP::Types::Unstable::ForkSessionRequest request) -> (ACP::Types::Unstable::ForkSessionResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::Unstable::ListProvidersRequest
+  # @rbs return: (ACP::Types::Unstable::ListProvidersResponse | ACP::RequestError)
+  def providers_list: (ACP::Types::Unstable::ListProvidersRequest request) -> (ACP::Types::Unstable::ListProvidersResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::Unstable::SetProviderRequest
+  # @rbs return: (ACP::Types::Unstable::SetProviderResponse | ACP::RequestError)
+  def providers_set: (ACP::Types::Unstable::SetProviderRequest request) -> (ACP::Types::Unstable::SetProviderResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::Unstable::DisableProviderRequest
+  # @rbs return: (ACP::Types::Unstable::DisableProviderResponse | ACP::RequestError)
+  def providers_disable: (ACP::Types::Unstable::DisableProviderRequest request) -> (ACP::Types::Unstable::DisableProviderResponse | ACP::RequestError)
+
   # 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. The notification goes first
@@ -151,13 +173,40 @@ class ACP::ClientConnection
   # @rbs return: (Hash[String, untyped] | ACP::RequestError)
   def ext_request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
 
+  # Always false off a handler thread.
+  #
+  # @rbs return: bool
+  def cancelled?: () -> bool
+
   # @rbs method: String
   # @rbs params: untyped
   # @rbs return: void
   def ext_notify: (String method, ?untyped params) -> void
 
+  # Unlike the mcp/message serve route, this send is not gated: a notification
+  # has no reply to carry a refusal, and the agent drops what it did not
+  # advertise.
+  #
+  # @rbs notification: ACP::Types::Unstable::MessageMcpNotification
+  # @rbs return: void
+  def mcp_message_notification: (ACP::Types::Unstable::MessageMcpNotification notification) -> void
+
   private
 
+  # The route is only registered when a handler serves it, but the agent's
+  # advertisement is only known after connect, so an unadvertised request
+  # still reaches the route and is refused there.
+  #
+  # @rbs return: Hash[String, ACP::Transport::Stdio::_Handler]
+  def mcp_requests: () -> Hash[String, ACP::Transport::Stdio::_Handler]
+
+  # The stable McpCapabilities has no acp field, so the gate re-reads the raw
+  # initialize reply with the unstable types when they are opted into.
+  #
+  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
+  # @rbs return: bool
+  def agent_mcp_advertised?: (Hash[String, untyped] | ACP::RequestError result) -> bool
+
   # @rbs type: ACP::AgentConnection::_Parser
   # @rbs result: (Hash[String, untyped] | ACP::RequestError)
   # @rbs return: untyped
@@ -237,6 +286,13 @@ class ACP::ClientConnection
   # @rbs return: (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
   def release_terminal: (untyped params) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
 
+  # The route is registered at start, before connect records the agent's
+  # advertisement, so an unadvertised request answers -32601 until then.
+  #
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
+  def mcp_message: (untyped params) -> (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
+
   # The routes are registered at start, before connect records the advertised
   # capabilities, so a request for an unadvertised mode answers -32602.
   #

data/sig/generated/acp/request_error.rbs

@@ -70,6 +70,14 @@ class ACP::RequestError
   # @rbs return: ACP::RequestError
   def self.unadvertised_mode: (String mode) -> ACP::RequestError
 
+  # unadvertised names a capability of the client's, this one a capability of
+  # the agent's: the same method-not-found code, with a message naming which
+  # side's advertisement is missing.
+  #
+  # @rbs capability: String
+  # @rbs return: ACP::RequestError
+  def self.unadvertised_agent: (String capability) -> ACP::RequestError
+
   # @rbs return: ACP::RequestError
   def self.internal_error: () -> ACP::RequestError
 

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

@@ -4,6 +4,19 @@
 # request, marks it when the peer's $/cancel_request arrives, and hands it to
 # the serving thread, whose handler can observe it and end the request early.
 class ACP::Transport::Cancellation
+  KEY: Symbol
+
+  # Connections read this to expose the serving state to their handlers and
+  # write it to carry serving identity onto a thread they spawn; nil off a
+  # serve thread.
+  #
+  # @rbs return: ACP::Transport::Cancellation?
+  def self.current: () -> ACP::Transport::Cancellation?
+
+  # @rbs cancellation: ACP::Transport::Cancellation?
+  # @rbs return: void
+  def self.current=: (ACP::Transport::Cancellation? cancellation) -> void
+
   @lock: Thread::Mutex
 
   @cancelled: bool

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

@@ -26,8 +26,6 @@ class ACP::Transport::Stdio
 
   CONNECTION_CLOSED: ACP::RequestError
 
-  SERVING_CANCEL: Symbol
-
   # @rbs input: _Reader
   # @rbs output: _Writer
   # @rbs logger: ACP::Transport::_Logger
@@ -59,6 +57,12 @@ class ACP::Transport::Stdio
   # @rbs return: void
   def cancel: (untyped id) -> void
 
+  # Each id is re-checked against the pending table, so one that settled
+  # between the snapshot and its cancel is not cancelled.
+  #
+  # @rbs return: void
+  def cancel_requests: () -> void
+
   # The cancellation of the request the calling thread is serving, or nil off
   # a serve thread. A handler observes the peer's $/cancel_request through it
   # and can end early with ACP::RequestError.request_cancelled; whatever it

data/sig/manual/acp/agent_connection/optional_method/disable_provider.rbs

@@ -0,0 +1,6 @@
+# rbs-inline does not emit `extend self`, so without this reopen the module's
+# methods aren't visible as singleton methods.
+
+module ACP::AgentConnection::OptionalMethod::DisableProvider
+  extend ::ACP::AgentConnection::OptionalMethod::DisableProvider
+end

data/sig/manual/acp/agent_connection/optional_method/fork_session.rbs

@@ -0,0 +1,6 @@
+# rbs-inline does not emit `extend self`, so without this reopen the module's
+# methods aren't visible as singleton methods.
+
+module ACP::AgentConnection::OptionalMethod::ForkSession
+  extend ::ACP::AgentConnection::OptionalMethod::ForkSession
+end

data/sig/manual/acp/agent_connection/optional_method/list_providers.rbs

@@ -0,0 +1,6 @@
+# rbs-inline does not emit `extend self`, so without this reopen the module's
+# methods aren't visible as singleton methods.
+
+module ACP::AgentConnection::OptionalMethod::ListProviders
+  extend ::ACP::AgentConnection::OptionalMethod::ListProviders
+end

data/sig/manual/acp/agent_connection/optional_method/set_provider.rbs

@@ -0,0 +1,6 @@
+# rbs-inline does not emit `extend self`, so without this reopen the module's
+# methods aren't visible as singleton methods.
+
+module ACP::AgentConnection::OptionalMethod::SetProvider
+  extend ::ACP::AgentConnection::OptionalMethod::SetProvider
+end

data/sig/manual/acp/agent_connection.rbs

@@ -36,6 +36,22 @@ class ACP::AgentConnection
     def logout: (ACP::Types::LogoutRequest) -> (ACP::Types::LogoutResponse | ACP::RequestError)
   end
 
+  interface _ForkSession
+    def fork_session: (ACP::Types::Unstable::ForkSessionRequest) -> (ACP::Types::Unstable::ForkSessionResponse | ACP::RequestError)
+  end
+
+  interface _ListProviders
+    def list_providers: (ACP::Types::Unstable::ListProvidersRequest) -> (ACP::Types::Unstable::ListProvidersResponse | ACP::RequestError)
+  end
+
+  interface _SetProvider
+    def set_provider: (ACP::Types::Unstable::SetProviderRequest) -> (ACP::Types::Unstable::SetProviderResponse | ACP::RequestError)
+  end
+
+  interface _DisableProvider
+    def disable_provider: (ACP::Types::Unstable::DisableProviderRequest) -> (ACP::Types::Unstable::DisableProviderResponse | ACP::RequestError)
+  end
+
   interface _ChangeSessionMode
     def change_session_mode: (ACP::Types::SetSessionModeRequest) -> (ACP::Types::SetSessionModeResponse | ACP::RequestError)
   end
@@ -53,6 +69,10 @@ class ACP::AgentConnection
     include _CloseSession
     include _DeleteSession
     include _Logout
+    include _ForkSession
+    include _ListProviders
+    include _SetProvider
+    include _DisableProvider
     include _ChangeSessionMode
     include _ChangeSessionConfigOption
   end
@@ -67,11 +87,18 @@ class ACP::AgentConnection
     def session_created: (ACP::Types::NewSessionResponse) -> void
   end
 
+  interface _McpMessageNotification
+    # Runs on the transport's reader thread, so it must return quickly.
+    def mcp_message_notification: (ACP::Types::Unstable::MessageMcpNotification notification) -> void
+  end
+
   # What an agent sees of ACP::AgentConnection::Client, so tests can pass a fake.
   interface _Client
     def update: (String session_id, ACP::Types::SessionUpdate::t update) -> void
     def available_commands: (String session_id, Array[ACP::Types::AvailableCommand] commands) -> void
     def request_permission: (ACP::Types::RequestPermissionRequest) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
+    def cancel_requests: () -> void
+    def cancelled?: () -> bool
     def read_text_file: (ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
     def write_text_file: (ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError)
     def create_terminal: (ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError)
@@ -81,6 +108,7 @@ class ACP::AgentConnection
     def release_terminal: (ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
     def create_elicitation: (ACP::Types::CreateElicitationRequest request) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError)
     def complete_elicitation: (ACP::Types::CompleteElicitationNotification notification) -> void
+    def mcp_message: (ACP::Types::Unstable::MessageMcpRequest request) -> (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError)
     def ext_request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
     def ext_notify: (String method, ?untyped params) -> void
     def capabilities: () -> ACP::Types::ClientCapabilities?
@@ -89,6 +117,8 @@ class ACP::AgentConnection
   interface _Peer
     def request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
     def notify: (String method, ?untyped params) -> void
+    def cancellation: () -> ACP::Transport::Cancellation?
+    def cancel_requests: () -> void
   end
 
   interface _Transport

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -38,10 +38,14 @@ files:
 - lib/acp/agent_connection/optional_method/authenticate.rb
 - lib/acp/agent_connection/optional_method/close_session.rb
 - lib/acp/agent_connection/optional_method/delete_session.rb
+- lib/acp/agent_connection/optional_method/disable_provider.rb
+- lib/acp/agent_connection/optional_method/fork_session.rb
+- lib/acp/agent_connection/optional_method/list_providers.rb
 - lib/acp/agent_connection/optional_method/list_sessions.rb
 - lib/acp/agent_connection/optional_method/load_session.rb
 - lib/acp/agent_connection/optional_method/logout.rb
 - lib/acp/agent_connection/optional_method/resume_session.rb
+- lib/acp/agent_connection/optional_method/set_provider.rb
 - lib/acp/agent_process.rb
 - lib/acp/client_connection.rb
 - lib/acp/extensions.rb
@@ -398,10 +402,14 @@ files:
 - sig/generated/acp/agent_connection/optional_method/authenticate.rbs
 - sig/generated/acp/agent_connection/optional_method/close_session.rbs
 - sig/generated/acp/agent_connection/optional_method/delete_session.rbs
+- sig/generated/acp/agent_connection/optional_method/disable_provider.rbs
+- sig/generated/acp/agent_connection/optional_method/fork_session.rbs
+- sig/generated/acp/agent_connection/optional_method/list_providers.rbs
 - sig/generated/acp/agent_connection/optional_method/list_sessions.rbs
 - sig/generated/acp/agent_connection/optional_method/load_session.rbs
 - sig/generated/acp/agent_connection/optional_method/logout.rbs
 - sig/generated/acp/agent_connection/optional_method/resume_session.rbs
+- sig/generated/acp/agent_connection/optional_method/set_provider.rbs
 - sig/generated/acp/agent_process.rbs
 - sig/generated/acp/client_connection.rbs
 - sig/generated/acp/extensions.rbs
@@ -756,10 +764,14 @@ files:
 - sig/manual/acp/agent_connection/optional_method/authenticate.rbs
 - sig/manual/acp/agent_connection/optional_method/close_session.rbs
 - sig/manual/acp/agent_connection/optional_method/delete_session.rbs
+- sig/manual/acp/agent_connection/optional_method/disable_provider.rbs
+- sig/manual/acp/agent_connection/optional_method/fork_session.rbs
+- sig/manual/acp/agent_connection/optional_method/list_providers.rbs
 - sig/manual/acp/agent_connection/optional_method/list_sessions.rbs
 - sig/manual/acp/agent_connection/optional_method/load_session.rbs
 - sig/manual/acp/agent_connection/optional_method/logout.rbs
 - sig/manual/acp/agent_connection/optional_method/resume_session.rbs
+- sig/manual/acp/agent_connection/optional_method/set_provider.rbs
 - sig/manual/acp/agent_process.rbs
 - sig/manual/acp/client_connection.rbs
 - sig/manual/acp/extensions.rbs
@@ -779,7 +791,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="