acp-sdk 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8a4bb93508ff8a9737b9b5b044e4b63e19ba87393490f10f522b9b63aee4396
-  data.tar.gz: 9e62dd726471fd718c2a234b9ea65bc90ca473c67d979e207b2702edd33b30b5
+  metadata.gz: 96418a5250fccc2c0eb4380e15309f7658f347bc91d5df3c1218cc3794389f48
+  data.tar.gz: 52c089fd1c4238da195880f4fcbf823452272de94a6c3f6ad3a2d7c06f0580d1
 SHA512:
-  metadata.gz: 50ef3954c1104ef512b757421bb0df10d3eb0be7f245c5a26c8641e815fa54d160a1d4d2c8369b9b41eb4b64affce206c584627650a5ce3446be09f88f2239b4
-  data.tar.gz: 0e505cd00fd0fef743dc1c047892db07b1ea4bf0999b3c0bff402fc10f73609a23fcbd4310b4a8deb7822fd06d8a64d1bab517426302004c205b3eee2972a104
+  metadata.gz: 84820ff6950c13e9d2fd30f5e5936f7951700af3622bfdc84af49cfcd6b7f24465e00d4889d2d451eaa01fc5091b6af7ecc103579c175d683f451e7ac27a86ce
+  data.tar.gz: 696efcc33f82fd2bc5ecd1a8e9843138c5be690e13ed4a72c955202c95af404c43a7c794868a1a0dad712174bb6ceaf71b0ab9d51bcf86e5954f6f6acdee3d61

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.11.0](https://github.com/bottrall/acp-sdk/compare/v0.10.0...v0.11.0) (2026-10-12)
+
+
+### Features
+
+* standardize ClientConnection senders on verb-noun naming ([#118](https://github.com/bottrall/acp-sdk/issues/118)) ([1b844ec](https://github.com/bottrall/acp-sdk/commit/1b844ecccef5b8714c5e3f2d0299713f0ee09e0f))
+
+
+### Bug Fixes
+
+* answer malformed elicitation params as invalid params ([#133](https://github.com/bottrall/acp-sdk/issues/133)) ([b9e1c51](https://github.com/bottrall/acp-sdk/commit/b9e1c510b60f78986998ba8be56c8a039488ee95)), closes [#125](https://github.com/bottrall/acp-sdk/issues/125)
+* answer the agent when a permission handler raises ([#134](https://github.com/bottrall/acp-sdk/issues/134)) ([a0f61a9](https://github.com/bottrall/acp-sdk/commit/a0f61a9db3589848fafadb7b4e19ad70b260f508)), closes [#124](https://github.com/bottrall/acp-sdk/issues/124)
+* cancel the echo agent's in-flight turn when its session is closed or deleted ([#136](https://github.com/bottrall/acp-sdk/issues/136)) ([e04a8c0](https://github.com/bottrall/acp-sdk/commit/e04a8c0bb672b569d68029c63eaee826d00c84fd)), closes [#130](https://github.com/bottrall/acp-sdk/issues/130)
+* **codegen:** keep the unset sentinel out of clearable to_h conversions ([#140](https://github.com/bottrall/acp-sdk/issues/140)) ([67769d7](https://github.com/bottrall/acp-sdk/commit/67769d7ff5d9f93dfe3f3ea2ba4ac71126caad60)), closes [#131](https://github.com/bottrall/acp-sdk/issues/131)
+* **codegen:** resolve primitive unions from each option's resolved shape ([#141](https://github.com/bottrall/acp-sdk/issues/141)) ([0b574ae](https://github.com/bottrall/acp-sdk/commit/0b574ae9d33c6c10eb0a00866b6c07f1601e01e8)), closes [#132](https://github.com/bottrall/acp-sdk/issues/132)
+* **codegen:** subsume union-variant twins into variant aliases ([#103](https://github.com/bottrall/acp-sdk/issues/103)) ([bdc0005](https://github.com/bottrall/acp-sdk/commit/bdc0005460c0fd133a09f10cf61f9f5717012e16)), closes [#93](https://github.com/bottrall/acp-sdk/issues/93)
+* echo slash commands followed only by whitespace ([#135](https://github.com/bottrall/acp-sdk/issues/135)) ([bb4bde6](https://github.com/bottrall/acp-sdk/commit/bb4bde6951ceb54ac87c92ec335dcdd319fd7b81)), closes [#129](https://github.com/bottrall/acp-sdk/issues/129)
+* read mcpCapabilities alone when deciding whether MCP is advertised ([#139](https://github.com/bottrall/acp-sdk/issues/139)) ([a6e882e](https://github.com/bottrall/acp-sdk/commit/a6e882ebf3c69f0aa8692100e81e61a085007a8b)), closes [#128](https://github.com/bottrall/acp-sdk/issues/128)
+* return a null or false result instead of "Connection closed" ([#137](https://github.com/bottrall/acp-sdk/issues/137)) ([19be64d](https://github.com/bottrall/acp-sdk/commit/19be64df6064e370bb23614a3b8df1056649cd3b)), closes [#127](https://github.com/bottrall/acp-sdk/issues/127)
+* settle a pending request when its response is malformed ([#138](https://github.com/bottrall/acp-sdk/issues/138)) ([7d0586e](https://github.com/bottrall/acp-sdk/commit/7d0586e856a54e5779e4d523bd0862ab57f44b10)), closes [#126](https://github.com/bottrall/acp-sdk/issues/126)
+
+## [0.10.0](https://github.com/bottrall/acp-sdk/compare/v0.9.0...v0.10.0) (2026-10-07)
+
+
+### 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. `set_session_mode` sends `session/set_mode`, and `set_session_config_option` sends `session/set_config_option` and returns the session's complete option list, which replaces any state held from an earlier reply. `fork_session` sends `session/fork`; it is unstable, so the request and response types exist only under `ACP::Types::Unstable` and calling it before `require 'acp/types/unstable'` raises `NameError`. `list_providers`, `set_provider` and `disable_provider` send `providers/list`, `providers/set` and `providers/disable` on the same unstable terms. A handler that raises is answered with `-32603` and the message `Internal error`, and the exception is only logged to the transport's logger.
 
 `ACP::AgentProcess.spawn` starts a command with args, env and cwd, wires its stdio to a new `ACP::ClientConnection` and starts it. The block receives the connection and the process handle (`pid`, plus `stderr` when captured), and the child is terminated — after its stdin is closed, with TERM and then KILL if it will not exit — when the block exits, so a raised block cannot leak the process. Without a block, `spawn` returns the process and calling `terminate` is yours. `stderr` is `:inherit` by default, so the child writes to your stderr; pass `:capture` to collect it on the process instead.
 
@@ -80,9 +81,9 @@ response = ACP::AgentProcess.spawn(
   updates: ->(notification) { show(notification) }
 ) do |connection|
   connection.connect(ACP::Types::InitializeRequest.new(protocol_version: 1))
-  session = connection.session_new(ACP::Types::NewSessionRequest.new(cwd: Dir.pwd, mcp_servers: []))
+  session = connection.new_session(ACP::Types::NewSessionRequest.new(cwd: Dir.pwd, mcp_servers: []))
   prompt = [ACP::Types::ContentBlock::Text.new(text: 'hello')]
-  connection.session_prompt(ACP::Types::PromptRequest.new(session_id: session.session_id, prompt:)) do |update|
+  connection.prompt_session(ACP::Types::PromptRequest.new(session_id: session.session_id, prompt:)) do |update|
     print update.content.text if update.is_a?(ACP::Types::SessionUpdate::AgentMessageChunk)
   end
 end
@@ -103,14 +104,23 @@ connection = ACP::ClientConnection.new(
 )
 ```
 
-- `session_prompt` and `session_load` yield the session's updates on the calling thread as they arrive and return once the agent replies. Updates outside those calls, such as the available commands after `session/new`, go to `updates`, which runs on the reader thread and must return quickly. `session_resume` does not take a block: the agent must not replay history on resume, so unlike `session_load` there is nothing to stream. `session_close` and `session_delete` end the session, discarding it on the agent, and return once the agent replies.
-- `permission` answers `session/request_permission` with an `ACP::Types::RequestPermissionResponse` or an `ACP::RequestError`. It runs on its own thread, so it may block while the user decides, and `session_cancel` can be sent meanwhile.
+- `prompt_session` and `load_session` yield the session's updates on the calling thread as they arrive and return once the agent replies. Updates outside those calls, such as the available commands after `session/new`, go to `updates`, which runs on the reader thread and must return quickly. `resume_session` does not take a block: the agent must not replay history on resume, so unlike `load_session` there is nothing to stream. `close_session` and `delete_session` end the session, discarding it on the agent, and return once the agent replies.
+- `permission` answers `session/request_permission` with an `ACP::Types::RequestPermissionResponse` or an `ACP::RequestError`. It runs on its own thread, so it may block while the user decides, and `cancel_session` can be sent meanwhile.
+- The agent may cancel any outstanding request with `$/cancel_request`: a handler that can end early checks `connection.cancelled?` — close over the connection when constructing it — and returns `ACP::RequestError.request_cancelled`, which is answered as `-32800`. The permission handler still sees the cancel on its own thread. Whatever the handler returns, the transport sends exactly one response.
 - `read_text_file` and `write_text_file` answer the agent's `fs/read_text_file` and `fs/write_text_file` with an `ACP::Types::ReadTextFileResponse`, an `ACP::Types::WriteTextFileResponse` or an `ACP::RequestError`. They are routed by the `fs` capabilities `connect` sends: a method the client does not advertise is answered with `-32601` without reaching the handler, and `connect` raises `ArgumentError` — before sending `initialize` — when the request advertises a capability that has no handler.
 - `create_terminal`, `terminal_output`, `wait_for_terminal_exit`, `kill_terminal` and `release_terminal` answer the agent's `terminal/create`, `terminal/output`, `terminal/wait_for_exit`, `terminal/kill` and `terminal/release` with the matching `ACP::Types` response or an `ACP::RequestError`. They are routed by the `terminal` capability `connect` sends, the same way as `fs`: a method the client does not advertise is answered with `-32601` without reaching the handler, and `connect` raises `ArgumentError` — before sending `initialize` — when the request advertises `terminal` with any of the five missing. The transport serves each request on its own thread, so `wait_for_terminal_exit` may block without holding up the others.
 - `elicitation` answers the agent's `elicitation/create` with an `ACP::Types::CreateElicitationResponse` or an `ACP::RequestError`, serving both form and url mode, and `complete_elicitation` receives the agent's `elicitation/complete` notification. They are routed by the `elicitation` capabilities `connect` sends: a request whose mode the client does not advertise is answered with `-32602` without reaching the handler, and `connect` raises `ArgumentError` — before sending `initialize` — when the request advertises `elicitation.form` or `elicitation.url` with no `elicitation` handler. The client tracks the elicitation ids of the url-mode requests it serves, so a completion for an unknown or already-completed id is ignored. `complete_elicitation` runs on the reader thread and must return quickly; it may be omitted, in which case completions are only tracked.
 
 Extensions work the same way in both directions: `extension_requests` and `extension_notifications` are hashes keyed by the raw `_`-prefixed wire name, `ext_request` sends one to the agent and returns its result as-is, and `ext_notify` sends an extension notification. A handler name without the `_` prefix raises `ArgumentError`, and an extension request nothing answers gets `-32601`.
 
+## Types
+
+Every ACP request, response and notification is a generated, frozen value class under `ACP::Types` with `from_h` and `to_h`. A few of its names are deliberate enough to deserve a note:
+
+- `CancelRequestNotification` and `CancelNotification` are different methods with different payloads: the former is the params of the JSON-RPC-level `$/cancel_request`, which the transport handles itself, the latter is the params of ACP's `session/cancel`. Both spellings are the schema's, not a typo.
+- The schema names `session/new`, `session/load`, `session/list` and `session/prompt`'s params and result `NewSessionRequest`, `LoadSessionRequest`, `ListSessionsRequest` and `PromptRequest`, so the wire-shaped spellings exist as alias constants: `ACP::Types::SessionNewRequest`, `SessionLoadRequest`, `SessionListRequest`, `SessionListResponse` and `SessionPromptRequest` are the same classes as their targets. Both names are public API and here to stay — use whichever reads better.
+- The schema's pure string enums are generated as constant modules, for building requests and matching responses without string literals: `ACP::Types::ToolKind::EDIT`, `ACP::Types::StopReason::CANCELLED`, `ACP::Types::PlanEntryPriority::HIGH`, `ACP::Types::Role::USER` and the rest. They carry no validation of their own — the generated `from_h` checks incoming values against the schema regardless of how you build outgoing ones.
+
 ## Unstable types
 
 Some protocol features are not part of the spec yet, so their schema lives in a separate unstable file: draft session updates (`plan_update`, `plan_removed`, `notice`, `compaction_update`, `compaction_summary_chunk`, `subagent_update`, `session_message`, `session_message_chunk`), `PromptResponse#usage`, the NE (next edit) and provider methods, and the matching capabilities. They are generated under `ACP::Types::Unstable` and load only when you opt in:
@@ -123,6 +133,8 @@ Until then, referencing `ACP::Types::Unstable` is a `NameError`, and the stable
 
 These types are **unstable**: they are not part of the ACP spec, agents and clients must not rely on the peer supporting them, and any of them may change or disappear between releases without a major version bump. When a stable schema absorbs one of them, the unstable twin goes away and the stable name stays.
 
+The connections route `session/fork`, the provider methods and `mcp/message`, but not every unstable method has routing yet: the NE methods (`nes/start`, `nes/suggest`, `nes/accept`, `nes/reject`, `nes/close`), the document notifications (`document/didOpen` and friends) and the unstable `ClientCapabilities` are generated as public API for callers wiring those methods at the transport level, and may gain connection routing later.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/bottrall/acp-sdk). See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and workflow. Everyone interacting in the project is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/lib/acp/agent_connection/client.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 class ACP::AgentConnection::Client
-  # @rbs @peer: ACP::AgentConnection::_Peer
+  # @rbs @peer: ACP::Transport::_Peer
+  # @rbs @mcp_advertised: bool
 
   # @dynamic capabilities, capabilities=
   attr_accessor :capabilities #: ACP::Types::ClientCapabilities?
 
-  # @rbs peer: ACP::AgentConnection::_Peer
+  # @rbs peer: ACP::Transport::_Peer
+  # @rbs mcp_advertised: bool
   # @rbs return: void
-  def initialize(peer:)
+  def initialize(peer:, mcp_advertised: false)
     @peer = peer
+    @mcp_advertised = mcp_advertised
     @capabilities = nil
   end
 
@@ -27,15 +30,24 @@ class ACP::AgentConnection::Client
     update(session_id, ACP::Types::SessionUpdate::AvailableCommandsUpdate.new(available_commands: commands))
   end
 
-  # Blocks the calling thread until the client answers or the connection
-  # closes.
-  #
   # @rbs request: ACP::Types::RequestPermissionRequest
   # @rbs return: ACP::Types::RequestPermissionResponse | ACP::RequestError
   def request_permission(request)
     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,9 +117,15 @@ class ACP::AgentConnection::Client
     @peer.notify('elicitation/complete', notification.to_h)
   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.
+  # @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
+
+  # Extension methods have no schema to parse the result into.
   #
   # @rbs method: String
   # @rbs params: untyped
@@ -128,8 +146,8 @@ class ACP::AgentConnection::Client
   private
 
   # @rbs rpc_method: String
-  # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs request: ACP::AgentConnection::_Response
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs request: ACP::Transport::_Response
   # @rbs return: untyped
   def call(rpc_method, type, request)
     result = @peer.request(rpc_method, request.to_h)
@@ -141,8 +159,8 @@ class ACP::AgentConnection::Client
   end
 
   # @rbs rpc_method: String
-  # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs request: ACP::AgentConnection::_Response
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs request: ACP::Transport::_Response
   # @rbs return: untyped
   def terminal_call(rpc_method, type, request)
     return ACP::RequestError.unadvertised('terminal') unless capabilities&.terminal

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

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

data/lib/acp/agent_connection/optional_method.rb

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

data/lib/acp/agent_connection.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class ACP::AgentConnection
-  # @rbs @transport: ACP::AgentConnection::_Transport
+  # @rbs @transport: ACP::Transport::_Transport
   # @rbs @capabilities: ACP::Types::AgentCapabilities
   # @rbs @agent_info: ACP::Types::Implementation?
   # @rbs @auth_methods: Array[ACP::Types::AuthMethod::t]
@@ -10,16 +10,6 @@ class ACP::AgentConnection
   # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
   # @rbs @logger: ACP::Transport::_Logger
 
-  PROTOCOL_VERSION = 1 #: Integer
-  OPTIONAL = [
-    ACP::AgentConnection::OptionalMethod::LoadSession,
-    ACP::AgentConnection::OptionalMethod::ListSessions,
-    ACP::AgentConnection::OptionalMethod::Authenticate,
-    ACP::AgentConnection::OptionalMethod::ResumeSession,
-    ACP::AgentConnection::OptionalMethod::CloseSession,
-    ACP::AgentConnection::OptionalMethod::DeleteSession,
-    ACP::AgentConnection::OptionalMethod::Logout
-  ].freeze #: Array[ACP::AgentConnection::_OptionalMethod]
   # The schema has no initialize capability for modes or config options: an
   # agent offers them per session, in its session responses, so they are
   # routed whenever the agent defines them.
@@ -28,7 +18,7 @@ class ACP::AgentConnection
     'session/set_config_option' => :change_session_config_option
   }.freeze #: Hash[String, Symbol]
 
-  # @rbs transport: ACP::AgentConnection::_Transport
+  # @rbs transport: ACP::Transport::_Transport
   # @rbs capabilities: ACP::Types::AgentCapabilities
   # @rbs agent_info: ACP::Types::Implementation?
   # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
@@ -61,15 +51,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),
@@ -81,7 +77,7 @@ class ACP::AgentConnection
 
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs client: ACP::AgentConnection::Client
-  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)]
   def requests(agent, client)
     # Safe: start drops the optional handlers initialize does not advertise
     # or the agent does not define, and checks the agent defines the rest.
@@ -101,13 +97,45 @@ 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::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  def unstable_requests(full)
+    return {} unless ACP::Types.unstable_enabled?
+
+    {
+      '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
 
+  # The unstable specs pair with the unstable request routes, which reference
+  # the unstable request classes, so both are only probed after the caller
+  # opted in with `require 'acp/types/unstable'`.
+  #
+  # @rbs return: Array[ACP::AgentConnection::OptionalMethod::Spec]
+  def optional_methods
+    specs = ACP::AgentConnection::OptionalMethod::SPECS
+    return specs unless ACP::Types.unstable_enabled?
+
+    specs + ACP::AgentConnection::OptionalMethod::UNSTABLE_SPECS
+  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,11 +151,30 @@ class ACP::AgentConnection
     agent.cancel(notification)
   end
 
+  # @rbs return: bool
+  def mcp_acp_advertised?
+    ACP::Protocol.mcp_acp_advertised?(@capabilities)
+  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
-  # @rbs &handle: (untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
-  # @rbs return: ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs &handle: (untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs return: ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
   def route(type, &)
     lambda do |params|
       request = type.from_h(params)
@@ -153,7 +200,7 @@ class ACP::AgentConnection
   # @rbs return: ACP::Types::InitializeResponse
   def initialize_response(auth_methods)
     ACP::Types::InitializeResponse.new(
-      protocol_version: PROTOCOL_VERSION,
+      protocol_version: ACP::Protocol::PROTOCOL_VERSION,
       agent_capabilities: @capabilities,
       auth_methods:,
       agent_info: @agent_info

data/lib/acp/agent_process.rb

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