acp-sdk 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 978b245a94b3cd60d3858ee42c3deaf9b687c8a6a1701ce54c684a5e434b2bce
-  data.tar.gz: b83adfe811bc7873455f9f81993061e7b2ea66d0a75b78645807fc44e08cd58b
+  metadata.gz: e8a4bb93508ff8a9737b9b5b044e4b63e19ba87393490f10f522b9b63aee4396
+  data.tar.gz: 9e62dd726471fd718c2a234b9ea65bc90ca473c67d979e207b2702edd33b30b5
 SHA512:
-  metadata.gz: 2907a71594882b7afd3ed8fe89b2e9520f139dc1c235a4e43bf836a2f127ae6264ce948d86885577daa6cd320078c6da831f4b8df89225201287276e17710c4e
-  data.tar.gz: 9191c0362932d37aaeb55666fb0b892505e448949f13e4173d0d9a0196ccebd16e56324f42db33f6c0d47fbec658bce6aac6e1bec4e4e9d4bdd4d6a1237ffc11
+  metadata.gz: 50ef3954c1104ef512b757421bb0df10d3eb0be7f245c5a26c8641e815fa54d160a1d4d2c8369b9b41eb4b64affce206c584627650a5ce3446be09f88f2239b4
+  data.tar.gz: 0e505cd00fd0fef743dc1c047892db07b1ea4bf0999b3c0bff402fc10f73609a23fcbd4310b4a8deb7822fd06d8a64d1bab517426302004c205b3eee2972a104

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* elicitation handlers on ACP::ClientConnection ([#78](https://github.com/bottrall/acp-sdk/issues/78)) ([94ee653](https://github.com/bottrall/acp-sdk/commit/94ee65374a0b463ccbd7ed57e05fe1ad76b08a62))
+
+
+### Bug Fixes
+
+* validate primitive and enum types when parsing params ([#79](https://github.com/bottrall/acp-sdk/issues/79)) ([624be63](https://github.com/bottrall/acp-sdk/commit/624be63f667468fba7c1a61064b84f43c226b060))
+
 ## [0.7.0](https://github.com/bottrall/acp-sdk/compare/v0.6.0...v0.7.0) (2026-10-05)
 
 

data/README.md

@@ -49,7 +49,7 @@ 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.
-- 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.
+- 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.
 - After a cancel, the agent must itself end the turn with `stopReason: cancelled`. `ACP::AgentConnection` does not enforce it.
@@ -107,9 +107,22 @@ connection = ACP::ClientConnection.new(
 - `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.
 - `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

@@ -136,7 +136,7 @@ class ACP::AgentConnection::Client
     return result if result.is_a?(ACP::RequestError)
 
     type.from_h(result)
-  rescue KeyError, TypeError, NoMethodError
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_response(result)
   end
 

data/lib/acp/agent_connection.rb

@@ -117,7 +117,7 @@ class ACP::AgentConnection
   # @rbs return: void
   def cancel(agent, params)
     notification = ACP::Types::CancelNotification.from_h(params)
-  rescue KeyError, TypeError, NoMethodError => e
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
     @logger.warn("dropped malformed session/cancel: #{e.class}: #{e.message}")
   else
     agent.cancel(notification)
@@ -131,6 +131,8 @@ class ACP::AgentConnection
   def route(type, &)
     lambda do |params|
       request = type.from_h(params)
+    rescue ACP::Types::ParseError => e
+      ACP::RequestError.invalid_params([e.message])
     rescue KeyError, TypeError, NoMethodError
       ACP::RequestError.invalid_params
     else

data/lib/acp/client_connection.rb

@@ -11,14 +11,19 @@ class ACP::ClientConnection
   #   (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError))?
   # @rbs @kill_terminal: (^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError))?
   # @rbs @release_terminal: (^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError))?
+  # @rbs @elicitation: (^(ACP::Types::CreateElicitationRequest) ->
+  #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
+  # @rbs @complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs @updates: ACP::ClientConnection::_UpdateHandler
   # @rbs @fs_capabilities: ACP::Types::FileSystemCapabilities?
   # @rbs @terminal: bool?
+  # @rbs @elicitation_capabilities: ACP::Types::ElicitationCapabilities?
   # @rbs @extension_requests: Hash[String, ^(untyped) -> untyped]
   # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
   # @rbs @lock: Thread::Mutex
   # @rbs @streams: Hash[String, Thread::Queue]
   # @rbs @pending_permissions: Hash[String, Array[Thread::Queue]]
+  # @rbs @outstanding_elicitations: Hash[String, bool]
   # @rbs @logger: ACP::Transport::_Logger
 
   PROTOCOL_VERSION = ACP::AgentConnection::PROTOCOL_VERSION #: Integer
@@ -39,6 +44,9 @@ class ACP::ClientConnection
   #   (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError))?
   # @rbs kill_terminal: (^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError))?
   # @rbs release_terminal: (^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError))?
+  # @rbs elicitation: (^(ACP::Types::CreateElicitationRequest) ->
+  #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
+  # @rbs complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs updates: ACP::ClientConnection::_UpdateHandler
   # @rbs extension_requests: Hash[String, ^(untyped) -> untyped]
   # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
@@ -54,6 +62,8 @@ class ACP::ClientConnection
     wait_for_terminal_exit: nil,
     kill_terminal: nil,
     release_terminal: nil,
+    elicitation: nil,
+    complete_elicitation: nil,
     updates: IGNORE,
     extension_requests: {},
     extension_notifications: {},
@@ -68,9 +78,12 @@ class ACP::ClientConnection
     @wait_for_terminal_exit = wait_for_terminal_exit
     @kill_terminal = kill_terminal
     @release_terminal = release_terminal
+    @elicitation = elicitation
+    @complete_elicitation = complete_elicitation
     @updates = updates
     @fs_capabilities = nil
     @terminal = nil
+    @elicitation_capabilities = nil
     @extension_requests = extension_requests
     @extension_notifications = extension_notifications
     extension_requests.each_key { |name| ACP::Extensions.validate_name(name) }
@@ -78,6 +91,7 @@ class ACP::ClientConnection
     @lock = Mutex.new
     @streams = {}
     @pending_permissions = {}
+    @outstanding_elicitations = {}
     @logger = logger
   end
 
@@ -92,9 +106,11 @@ class ACP::ClientConnection
         'terminal/output' => method(:terminal_output),
         'terminal/wait_for_exit' => method(:wait_for_terminal_exit),
         'terminal/kill' => method(:kill_terminal),
-        'terminal/release' => method(:release_terminal)
+        'terminal/release' => method(:release_terminal),
+        'elicitation/create' => method(:create_elicitation)
       }.merge(@extension_requests),
-      notifications: { 'session/update' => method(:dispatch) }.merge(@extension_notifications)
+      notifications: { 'session/update' => method(:dispatch),
+                       'elicitation/complete' => method(:complete_elicitation) }.merge(@extension_notifications)
     )
   end
 
@@ -116,8 +132,15 @@ class ACP::ClientConnection
       raise ArgumentError, "initialize advertises terminal methods no handler serves: #{unserved.join(', ')}"
     end
 
+    elicitation = request.client_capabilities&.elicitation
+    unserved = unserved_elicitation_modes(elicitation)
+    unless unserved.empty?
+      raise ArgumentError, "initialize advertises elicitation modes no handler serves: #{unserved.join(', ')}"
+    end
+
     @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)
 
@@ -246,7 +269,7 @@ class ACP::ClientConnection
     return result if result.is_a?(ACP::RequestError)
 
     type.from_h(result)
-  rescue KeyError, TypeError, NoMethodError
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_response(result)
   end
 
@@ -295,7 +318,7 @@ class ACP::ClientConnection
   # @rbs return: void
   def dispatch(params)
     notification = ACP::Types::SessionNotification.from_h(params)
-  rescue KeyError, TypeError, NoMethodError => e
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
     @logger.warn("dropped malformed session/update: #{e.class}: #{e.message}")
   else
     queue = @lock.synchronize { @streams[notification.session_id]&.push(notification.update) }
@@ -310,6 +333,8 @@ class ACP::ClientConnection
   # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
   def request_permission(params)
     request = ACP::Types::RequestPermissionRequest.from_h(params)
+  rescue ACP::Types::ParseError => e
+    ACP::RequestError.invalid_params([e.message])
   rescue KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_params
   else
@@ -363,6 +388,8 @@ class ACP::ClientConnection
     return ACP::RequestError.unadvertised('fs.readTextFile') unless @fs_capabilities&.read_text_file
 
     request = ACP::Types::ReadTextFileRequest.from_h(params)
+  rescue ACP::Types::ParseError => e
+    ACP::RequestError.invalid_params([e.message])
   rescue KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_params
   else
@@ -377,6 +404,8 @@ class ACP::ClientConnection
     return ACP::RequestError.unadvertised('fs.writeTextFile') unless @fs_capabilities&.write_text_file
 
     request = ACP::Types::WriteTextFileRequest.from_h(params)
+  rescue ACP::Types::ParseError => e
+    ACP::RequestError.invalid_params([e.message])
   rescue KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_params
   else
@@ -461,6 +490,54 @@ class ACP::ClientConnection
     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.
+  #
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::CreateElicitationResponse | ACP::RequestError)
+  def create_elicitation(params)
+    request = ACP::Types::CreateElicitationRequest.from_h(params)
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_params
+  else
+    case request.mode
+    when ACP::Types::CreateElicitationRequest::Mode::Form
+      return ACP::RequestError.unadvertised_mode('elicitation.form') unless @elicitation_capabilities&.form
+    when ACP::Types::CreateElicitationRequest::Mode::Url
+      return ACP::RequestError.unadvertised_mode('elicitation.url') unless @elicitation_capabilities&.url
+
+      register_elicitation(request.mode.elicitation_id)
+    else
+      return ACP::RequestError.unadvertised_mode("elicitation.#{request.mode['mode']}")
+    end
+
+    # Safe: connect refuses an advertised mode no handler serves.
+    handler = @elicitation #: ^(ACP::Types::CreateElicitationRequest) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError)
+    handler.call(request)
+  end
+
+  # The spec requires a completion for an unknown or already-completed
+  # elicitation id to be ignored, so only an id registered by a served
+  # url-mode request reaches the handler. It runs on the transport's reader
+  # thread, so it must return quickly.
+  #
+  # @rbs params: untyped
+  # @rbs return: void
+  def complete_elicitation(params)
+    notification = ACP::Types::CompleteElicitationNotification.from_h(params)
+  rescue KeyError, TypeError, NoMethodError => e
+    @logger.warn("dropped malformed elicitation/complete: #{e.class}: #{e.message}")
+  else
+    known = @lock.synchronize { @outstanding_elicitations.delete(notification.elicitation_id) }
+    @complete_elicitation&.call(notification) if known
+  end
+
+  # @rbs elicitation_id: String
+  # @rbs return: void
+  def register_elicitation(elicitation_id)
+    @lock.synchronize { @outstanding_elicitations[elicitation_id] = true }
+  end
+
   # The fs capabilities initialize advertises that no injected handler serves.
   #
   # @rbs capabilities: ACP::Types::FileSystemCapabilities?
@@ -486,4 +563,16 @@ class ACP::ClientConnection
       'terminal.release' => capabilities && !@release_terminal
     }.select { |_, unserved| unserved }.keys
   end
+
+  # The elicitation capabilities initialize advertises that no injected
+  # handler serves.
+  #
+  # @rbs capabilities: ACP::Types::ElicitationCapabilities?
+  # @rbs return: Array[String]
+  def unserved_elicitation_modes(capabilities)
+    {
+      'elicitation.form' => capabilities&.form && !@elicitation,
+      'elicitation.url' => capabilities&.url && !@elicitation
+    }.select { |_, unserved| unserved }.keys
+  end
 end

data/lib/acp/request_error.rb

@@ -54,9 +54,10 @@ class ACP::RequestError
     new(code: METHOD_NOT_FOUND, message: 'Method not found', data: method && { method: method })
   end
 
+  # @rbs errors: Array[String]?
   # @rbs return: ACP::RequestError
-  def self.invalid_params
-    new(code: INVALID_PARAMS, message: 'Invalid params')
+  def self.invalid_params(errors = nil)
+    new(code: INVALID_PARAMS, message: 'Invalid params', data: errors && { errors: errors })
   end
 
   # The method-not-found code for a method the client's capabilities do not
@@ -69,6 +70,18 @@ class ACP::RequestError
     new(code: METHOD_NOT_FOUND, message: "Client does not advertise #{capability}")
   end
 
+  # The invalid-params code for a request whose mode the client's
+  # capabilities do not advertise, with a message that names the mode so it
+  # can be told apart from malformed params. The spec gives elicitation a
+  # mode in its params, so an unadvertised one is invalid params rather than
+  # method not found.
+  #
+  # @rbs mode: String
+  # @rbs return: ACP::RequestError
+  def self.unadvertised_mode(mode)
+    new(code: INVALID_PARAMS, message: "Client does not advertise #{mode}")
+  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,25 @@
+# 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
+  # @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

data/lib/acp/transport/stdio.rb

@@ -13,6 +13,7 @@ class ACP::Transport::Stdio
   # @rbs @write_lock: Thread::Mutex
   # @rbs @lock: Thread::Mutex
   # @rbs @pending: Hash[untyped, Thread::Queue]
+  # @rbs @serving: Hash[untyped, ACP::Transport::Cancellation]
   # @rbs @next_id: Integer
   # @rbs @closed: bool
   # @rbs @logger: ACP::Transport::_Logger
@@ -21,6 +22,9 @@ 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
@@ -31,6 +35,7 @@ class ACP::Transport::Stdio
     @write_lock = Mutex.new
     @lock = Mutex.new
     @pending = {}
+    @serving = {}
     @next_id = 0
     @closed = false
     @logger = logger
@@ -70,6 +75,26 @@ class ACP::Transport::Stdio
     write({ 'jsonrpc' => '2.0', 'method' => method, 'params' => params }.compact)
   end
 
+  # The waiting caller is released only by the peer's answer, which the spec
+  # requires to be either a result or the -32800 error.
+  #
+  # @rbs id: untyped
+  # @rbs return: void
+  def cancel(id)
+    pending = @lock.synchronize { @pending.key?(id) }
+    notify('$/cancel_request', { 'requestId' => id }) if pending
+  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
+  # returns, the transport sends exactly one response.
+  #
+  # @rbs return: ACP::Transport::Cancellation?
+  def cancellation
+    Thread.current[SERVING_CANCEL] #: ACP::Transport::Cancellation?
+  end
+
   private
 
   # @rbs line: String
@@ -91,7 +116,11 @@ class ACP::Transport::Stdio
   def route(message, requests, notifications)
     method = message['method']
     error = message['error']
-    if method.is_a?(String) && message.key?('id')
+    if method == '$/cancel_request' && !message.key?('id')
+      # Cancellation is transport-owned: the notification targets a request
+      # the transport is serving, not application state.
+      cancel_request(message['params'])
+    elsif method.is_a?(String) && message.key?('id')
       serve(requests[method], message['id'], message['params'], method)
     elsif method.is_a?(String)
       # Run on the reader thread so notifications (session/update) keep their
@@ -136,7 +165,9 @@ class ACP::Transport::Stdio
   # @rbs method: String
   # @rbs return: void
   def serve(handler, id, params, method)
+    cancellation = register_serving(id)
     Thread.new do
+      Thread.current[SERVING_CANCEL] = cancellation
       outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
       case outcome
       when ACP::Transport::Reply
@@ -144,9 +175,44 @@ class ACP::Transport::Stdio
         quietly('reply after callback', &outcome.after)
       else reply(id, outcome)
       end
+    ensure
+      unregister_serving(id)
     end
   end
 
+  # Registered before the serve thread starts so a cancel racing the request
+  # cannot be missed, and dropped once the response is on the wire so later
+  # cancels for the id are ignored.
+  #
+  # @rbs id: untyped
+  # @rbs return: ACP::Transport::Cancellation
+  def register_serving(id)
+    cancellation = ACP::Transport::Cancellation.new
+    @lock.synchronize { @serving[id] = cancellation }
+    cancellation
+  end
+
+  # @rbs id: untyped
+  # @rbs return: void
+  def unregister_serving(id)
+    @lock.synchronize { @serving.delete(id) }
+  end
+
+  # A notification has no reply to carry a malformed params failure, so one
+  # is warned and dropped rather than answered.
+  #
+  # @rbs params: untyped
+  # @rbs return: void
+  def cancel_request(params)
+    id = params.is_a?(Hash) ? params['requestId'] : nil
+    unless id.is_a?(String) || id.is_a?(Integer)
+      return @logger.warn('dropped malformed $/cancel_request: missing requestId')
+    end
+
+    cancellation = @lock.synchronize { @serving[id] }
+    cancellation&.cancel
+  end
+
   # For code with no reply to carry an error: a notification handler, or a
   # Reply's after once the reply is on the wire. An exception must not kill
   # the reader thread or print a thread report.

data/lib/acp/types/agent_auth_capabilities.rb

@@ -21,7 +21,10 @@ class ACP::Types::AgentAuthCapabilities
   # @rbs hash: Hash[String, untyped]
   # @rbs return: ACP::Types::AgentAuthCapabilities
   def self.from_h(hash)
-    new(logout: hash['logout']&.then { |value| ACP::Types::LogoutCapabilities.from_h(value) }, meta: hash['_meta'])
+    new(
+      logout: ACP::Types::Check.object(hash['logout'], 'logout', ACP::Types::LogoutCapabilities, allow_nil: true),
+      meta: hash['_meta']
+    )
   end
 
   # @rbs return: Hash[String, untyped]

data/lib/acp/types/agent_capabilities.rb

@@ -49,11 +49,26 @@ class ACP::Types::AgentCapabilities
   # @rbs return: ACP::Types::AgentCapabilities
   def self.from_h(hash)
     new(
-      load_session: hash['loadSession'],
-      prompt_capabilities: hash['promptCapabilities']&.then { |value| ACP::Types::PromptCapabilities.from_h(value) },
-      mcp_capabilities: hash['mcpCapabilities']&.then { |value| ACP::Types::McpCapabilities.from_h(value) },
-      session_capabilities: hash['sessionCapabilities']&.then { |value| ACP::Types::SessionCapabilities.from_h(value) },
-      auth: hash['auth']&.then { |value| ACP::Types::AgentAuthCapabilities.from_h(value) },
+      load_session: ACP::Types::Check.boolean(hash['loadSession'], 'loadSession', allow_nil: true),
+      prompt_capabilities: ACP::Types::Check.object(
+        hash['promptCapabilities'],
+        'promptCapabilities',
+        ACP::Types::PromptCapabilities,
+        allow_nil: true
+      ),
+      mcp_capabilities: ACP::Types::Check.object(
+        hash['mcpCapabilities'],
+        'mcpCapabilities',
+        ACP::Types::McpCapabilities,
+        allow_nil: true
+      ),
+      session_capabilities: ACP::Types::Check.object(
+        hash['sessionCapabilities'],
+        'sessionCapabilities',
+        ACP::Types::SessionCapabilities,
+        allow_nil: true
+      ),
+      auth: ACP::Types::Check.object(hash['auth'], 'auth', ACP::Types::AgentAuthCapabilities, allow_nil: true),
       meta: hash['_meta']
     )
   end

data/lib/acp/types/annotations.rb

@@ -31,10 +31,13 @@ class ACP::Types::Annotations
   # @rbs hash: Hash[String, untyped]
   # @rbs return: ACP::Types::Annotations
   def self.from_h(hash)
+    audience = ACP::Types::Check.array(hash['audience'], 'audience', allow_nil: true) do |item, path|
+      ACP::Types::Check.enum(item, path, %w[assistant user])
+    end
     new(
-      audience: hash['audience'],
-      last_modified: hash['lastModified'],
-      priority: hash['priority'],
+      audience:,
+      last_modified: ACP::Types::Check.string(hash['lastModified'], 'lastModified', allow_nil: true),
+      priority: ACP::Types::Check.number(hash['priority'], 'priority', allow_nil: true),
       meta: hash['_meta']
     )
   end

data/lib/acp/types/audio_content.rb

@@ -32,9 +32,14 @@ class ACP::Types::AudioContent
   # @rbs return: ACP::Types::AudioContent
   def self.from_h(hash)
     new(
-      annotations: hash['annotations']&.then { |value| ACP::Types::Annotations.from_h(value) },
-      data: hash.fetch('data'),
-      mime_type: hash.fetch('mimeType'),
+      annotations: ACP::Types::Check.object(
+        hash['annotations'],
+        'annotations',
+        ACP::Types::Annotations,
+        allow_nil: true
+      ),
+      data: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'data'), 'data'),
+      mime_type: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'mimeType'), 'mimeType'),
       meta: hash['_meta']
     )
   end

data/lib/acp/types/auth_capabilities.rb

@@ -21,7 +21,7 @@ class ACP::Types::AuthCapabilities
   # @rbs hash: Hash[String, untyped]
   # @rbs return: ACP::Types::AuthCapabilities
   def self.from_h(hash)
-    new(terminal: hash['terminal'], meta: hash['_meta'])
+    new(terminal: ACP::Types::Check.boolean(hash['terminal'], 'terminal', allow_nil: true), meta: hash['_meta'])
   end
 
   # @rbs return: Hash[String, untyped]

data/lib/acp/types/auth_method/terminal.rb

@@ -41,12 +41,18 @@ class ACP::Types::AuthMethod::Terminal
   # @rbs hash: Hash[String, untyped]
   # @rbs return: ACP::Types::AuthMethod::Terminal
   def self.from_h(hash)
+    args = ACP::Types::Check.array(hash['args'], 'args', allow_nil: true) do |item, path|
+      ACP::Types::Check.string(item, path)
+    end
+    env = ACP::Types::Check.hash(hash['env'], 'env', allow_nil: true) do |value, path|
+      ACP::Types::Check.string(value, path)
+    end
     new(
-      id: hash.fetch('id'),
-      name: hash.fetch('name'),
-      description: hash['description'],
-      args: hash['args'],
-      env: hash['env'],
+      id: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'id'), 'id'),
+      name: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'name'), 'name'),
+      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
+      args:,
+      env:,
       meta: hash['_meta']
     )
   end

data/lib/acp/types/auth_method_agent.rb

@@ -31,7 +31,12 @@ class ACP::Types::AuthMethodAgent
   # @rbs hash: Hash[String, untyped]
   # @rbs return: ACP::Types::AuthMethodAgent
   def self.from_h(hash)
-    new(id: hash.fetch('id'), name: hash.fetch('name'), description: hash['description'], meta: hash['_meta'])
+    new(
+      id: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'id'), 'id'),
+      name: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'name'), 'name'),
+      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
+      meta: hash['_meta']
+    )
   end
 
   # @rbs return: Hash[String, untyped]

data/lib/acp/types/auth_method_terminal.rb

@@ -41,12 +41,18 @@ class ACP::Types::AuthMethodTerminal
   # @rbs hash: Hash[String, untyped]
   # @rbs return: ACP::Types::AuthMethodTerminal
   def self.from_h(hash)
+    args = ACP::Types::Check.array(hash['args'], 'args', allow_nil: true) do |item, path|
+      ACP::Types::Check.string(item, path)
+    end
+    env = ACP::Types::Check.hash(hash['env'], 'env', allow_nil: true) do |value, path|
+      ACP::Types::Check.string(value, path)
+    end
     new(
-      id: hash.fetch('id'),
-      name: hash.fetch('name'),
-      description: hash['description'],
-      args: hash['args'],
-      env: hash['env'],
+      id: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'id'), 'id'),
+      name: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'name'), 'name'),
+      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
+      args:,
+      env:,
       meta: hash['_meta']
     )
   end