acp-sdk 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0b8b181c4cbd41a411868aecdf9f34d0356b490526c446a962287a5a3ae01cc
-  data.tar.gz: 1376e6d42bc4369de51a645ed423a563e7aa9b35c4c49b060c77a983cb2c603c
+  metadata.gz: e0d983006184ce11ac51e9361062aa6878c01d348645f41fe226423db5d72e8b
+  data.tar.gz: 0d50ff69cb0c6cc743d75dcd3fd943a9ddeaa4469a8f1e8d6e54be811e3c3b39
 SHA512:
-  metadata.gz: 6c5d6271be17f17e203c178664ad6de2234c4b1a7b1857663c1ebb20bdbe1fa3c282db70ac6fe3c3e6b9647dfaadbe761bd018972943393a0cb3dec3d10bb2a3
-  data.tar.gz: 9ca3cae203c38496096dd020403054daaa4cb6797183c95b04a75c045f4a8aff89754a07af0fd74eb4c2a45f48dbc6d7c64352faf572000f118130d473283f0b
+  metadata.gz: 4296fbbf1fa985cb3913f2019528c06658fd8fcac285a238abf79073d2d5eb13d081e69da57f05476569967189f732c804f6dc851e291709c0b4052572b17d9f
+  data.tar.gz: 8f0a5bedfa32615f867111297c4fc593f2b567fd77a55e76dda4eabe57bd8494e225de93b470f1ac294f4b99a57797fda4d7f69704693fb8cd322e65fe650f59

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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)
+
+
+### Features
+
+* $/cancel_request in ACP::Transport::Stdio ([#82](https://github.com/bottrall/acp-sdk/issues/82)) ([8679883](https://github.com/bottrall/acp-sdk/commit/86798837ce9e35949c7cc3770e52f3191d81bc6f))
+* opt-in types for the unstable schema ([#83](https://github.com/bottrall/acp-sdk/issues/83)) ([a49a5cc](https://github.com/bottrall/acp-sdk/commit/a49a5ccba84e599fc8fae95fe2336a4eb3169835))
+
 ## [0.8.0](https://github.com/bottrall/acp-sdk/compare/v0.7.0...v0.8.0) (2026-10-06)
 
 

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,12 +106,25 @@ 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.
 
 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`.
 
+## 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:
+
+```ruby
+require 'acp/types/unstable'
+```
+
+Until then, referencing `ACP::Types::Unstable` is a `NameError`, and the stable `ACP::Types` namespace is byte-identical either way: types the unstable schema shares with the stable one resolve to the same generated classes, so opting in adds names without changing or duplicating any stable one.
+
+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.
+
 ## 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

@@ -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/sdk.rb

@@ -9,5 +9,7 @@ root = __dir__ #: String
 loader = Zeitwerk::Loader.new
 loader.tag = 'acp-sdk'
 loader.push_dir(root, namespace: ACP)
-loader.ignore(__FILE__, "#{root}/version.rb")
+# The unstable types load only through `require 'acp/types/unstable'`, so
+# Zeitwerk must not map them.
+loader.ignore(__FILE__, "#{root}/version.rb", "#{root}/types/unstable.rb", "#{root}/types/unstable")
 loader.setup

data/lib/acp/transport/cancellation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Whether the peer cancelled one request. The transport creates one per served
+# 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
+
+  # @rbs return: void
+  def initialize
+    @lock = Mutex.new
+    @cancelled = false
+  end
+
+  # @rbs return: void
+  def cancel
+    @lock.synchronize { @cancelled = true }
+  end
+
+  # @rbs return: bool
+  def cancelled?
+    @lock.synchronize { @cancelled }
+  end
+end