acp-sdk 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59dca9a568751a3b4c29c1ff4afdd9ad12e997689d5eb3a4782f2a4c5ced81b0
-  data.tar.gz: 99bde6bbc81d16012a6d9b3654bf15f15a35a40713f3d6dbbe686557f182ac50
+  metadata.gz: 77ac970489b956c7216d4c94a8d5cc6e7bf3fe5bfd10110cb8558c119f58f69d
+  data.tar.gz: 29ec919463eb48d06811aa8b6c736163fd7872348ce99f3f8cdc10c5670bf8c4
 SHA512:
-  metadata.gz: f803ca1e9d3dae3b791cebe930d49c221b2cd3f68df6cc5734bc3e40103af0d101db4447851596c2f6834b855f08a110c24455b06c517aa62e51b95a23cbdfd2
-  data.tar.gz: 844f53d23060359a77314f196fdeab023a7ded7c67fdea9f1a75b80bb28db3efb2421977001c13b3ec37f84479f6b9bf816e53a4a8da92c89bc58ee211b88ab8
+  metadata.gz: acf89beeb444ff33ac273aececd55d645792fe591f346cbdce0a099b6b6bff4eedb4025cceadd3a46ec62253c85b111c0149466960707b3feaa92623dab600a8
+  data.tar.gz: 92fba44ccd9334876fa8cb689728a7a19cc3d473bf1e7ee27fe215d72e48952e04bc9c0428609e31e883bdef6986e1ec7b4c9383d8a37271646593b33ff069bd

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.5.0](https://github.com/bottrall/acp-sdk/compare/v0.4.0...v0.5.0) (2026-10-04)
+
+
+### Features
+
+* add authenticate and logout to ACP::ClientConnection ([#63](https://github.com/bottrall/acp-sdk/issues/63)) ([460585a](https://github.com/bottrall/acp-sdk/commit/460585a9a9401e35725ea379432694d9b76f35b6))
+* add session_set_mode and session_set_config_option to ACP::ClientConnection ([#66](https://github.com/bottrall/acp-sdk/issues/66)) ([994179f](https://github.com/bottrall/acp-sdk/commit/994179f9ab51918bee7d29c8b473e0f05a55a7ad))
+* add session/resume, session/close and session/delete to the client ([#65](https://github.com/bottrall/acp-sdk/issues/65)) ([4af834a](https://github.com/bottrall/acp-sdk/commit/4af834a5bc519753bad36d41efba902bcddc296b)), closes [#37](https://github.com/bottrall/acp-sdk/issues/37)
+* elicitation on ACP::AgentConnection::Client ([#67](https://github.com/bottrall/acp-sdk/issues/67)) ([7d3212a](https://github.com/bottrall/acp-sdk/commit/7d3212a82ec6392351d8df1349b2fc21bf0bf030)), closes [#41](https://github.com/bottrall/acp-sdk/issues/41)
+* filesystem handlers on ACP::ClientConnection ([#68](https://github.com/bottrall/acp-sdk/issues/68)) ([053f091](https://github.com/bottrall/acp-sdk/commit/053f0910adc3a7016bf1769099a54655f41bb9a6))
+* injectable logger for dropped messages and swallowed errors ([#59](https://github.com/bottrall/acp-sdk/issues/59)) ([e66a306](https://github.com/bottrall/acp-sdk/commit/e66a30622922717d1be6d27c5b9a2931643fcd6b))
+
+
+### Bug Fixes
+
+* call ACP::RequestError.unadvertised in elicitation capability checks ([#69](https://github.com/bottrall/acp-sdk/issues/69)) ([fda6dad](https://github.com/bottrall/acp-sdk/commit/fda6dad13e7fe308b5ff63e4c9e6fa9eef6e8274))
+* only advertise terminal auth methods to clients that support them ([#61](https://github.com/bottrall/acp-sdk/issues/61)) ([1d2674a](https://github.com/bottrall/acp-sdk/commit/1d2674a978d938834d69d2c68df4f2c918ea801c)), closes [#33](https://github.com/bottrall/acp-sdk/issues/33)
+* refuse overlapping streaming calls for the same session ([#64](https://github.com/bottrall/acp-sdk/issues/64)) ([a3a5b34](https://github.com/bottrall/acp-sdk/commit/a3a5b343f0ba2555b62643577226166fada27485))
+* reject an unsupported protocol version in ACP::ClientConnection#connect ([#62](https://github.com/bottrall/acp-sdk/issues/62)) ([6980b32](https://github.com/bottrall/acp-sdk/commit/6980b328bcec997ae68c6af9077d623a73c15d39)), closes [#34](https://github.com/bottrall/acp-sdk/issues/34)
+
+## [0.4.0](https://github.com/bottrall/acp-sdk/compare/v0.3.0...v0.4.0) (2026-10-02)
+
+
+### Features
+
+* bump the vendored schema to v1.24.1 ([#58](https://github.com/bottrall/acp-sdk/issues/58)) ([56d8505](https://github.com/bottrall/acp-sdk/commit/56d85057a1c34f1a089580a78b7b66973c92a9e8))
+
+
+### Bug Fixes
+
+* return a RequestError for malformed peer responses ([#57](https://github.com/bottrall/acp-sdk/issues/57)) ([e52d479](https://github.com/bottrall/acp-sdk/commit/e52d479ce8cd6de37f753e7580d5562f1ace2d7d)), closes [#27](https://github.com/bottrall/acp-sdk/issues/27)
+* route logout on ACP::AgentConnection ([#55](https://github.com/bottrall/acp-sdk/issues/55)) ([3b2b144](https://github.com/bottrall/acp-sdk/commit/3b2b1444c502380a058231884c66efe26bb3770a)), closes [#26](https://github.com/bottrall/acp-sdk/issues/26)
+
 ## [0.3.0](https://github.com/bottrall/acp-sdk/compare/v0.2.0...v0.3.0) (2026-10-02)
 
 

data/README.md

@@ -48,19 +48,20 @@ 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; `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.
 - 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.
 - `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.
 - `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.
+- `client.create_elicitation` takes an `ACP::Types::CreateElicitationRequest` and returns an `ACP::Types::CreateElicitationResponse` or an `ACP::RequestError`. Unless `client.capabilities` advertises the `elicitation.form` or `elicitation.url` mode the request asks for, it returns `-32601` without sending anything to the client. A response action the SDK does not know comes through as the raw hash the client sent. `client.complete_elicitation` takes an `ACP::Types::CompleteElicitationNotification` and sends nothing, returning `-32601`, unless the client advertises `elicitation.url`, since only URL-mode elicitations are completed.
 
-[`examples/echo_agent.rb`](https://github.com/bottrall/acp-sdk/blob/main/examples/echo_agent.rb) is a complete agent that streams updates, asks permission, handles cancellation, reads and writes files and runs commands through the client (`/read <path>`, `/write <path> <text>` and `/run <command> [args]`, each advertised as a slash command only when the client supports it), and supports `session/load` and `session/list`.
+[`examples/echo_agent.rb`](https://github.com/bottrall/acp-sdk/blob/main/examples/echo_agent.rb) is a complete agent that streams updates, asks permission, handles cancellation, reads and writes files and runs commands through the client (`/read <path>`, `/write <path> <text>` and `/run <command> [args]`, each advertised as a slash command only when the client supports it), and supports `session/load`, `session/list`, `session/resume`, `session/close` and `session/delete`.
 
 ## Driving an agent
 
-`ACP::ClientConnection` is the other side of the same transport. Each method takes the request's generated `ACP::Types` object and returns its response type or the agent's `ACP::RequestError`. `connect` sends `initialize`, since Ruby reserves that name for the constructor.
+`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.
 
 `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.
 
@@ -90,12 +91,18 @@ Any transport over a pair of IOs works too, so the connection can still be wired
 connection = ACP::ClientConnection.new(
   transport: ACP::Transport::Stdio.new(input: some_io, output: other_io),
   permission: ->(request) { ask_the_user(request) },
+  read_text_file: ->(request) { ACP::Types::ReadTextFileResponse.new(content: File.read(request.path)) },
+  write_text_file: ->(request) {
+    File.write(request.path, request.content)
+    ACP::Types::WriteTextFileResponse.new
+  },
   updates: ->(notification) { show(notification) }
 )
 ```
 
-- `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_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.
+- `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.
 
 ## Contributing
 

data/lib/acp/agent_connection/client.rb

@@ -39,7 +39,7 @@ class ACP::AgentConnection::Client
   # @rbs request: ACP::Types::ReadTextFileRequest
   # @rbs return: ACP::Types::ReadTextFileResponse | ACP::RequestError
   def read_text_file(request)
-    return unadvertised('fs.readTextFile') unless capabilities&.fs&.read_text_file
+    return ACP::RequestError.unadvertised('fs.readTextFile') unless capabilities&.fs&.read_text_file
 
     call('fs/read_text_file', ACP::Types::ReadTextFileResponse, request)
   end
@@ -47,7 +47,7 @@ class ACP::AgentConnection::Client
   # @rbs request: ACP::Types::WriteTextFileRequest
   # @rbs return: ACP::Types::WriteTextFileResponse | ACP::RequestError
   def write_text_file(request)
-    return unadvertised('fs.writeTextFile') unless capabilities&.fs&.write_text_file
+    return ACP::RequestError.unadvertised('fs.writeTextFile') unless capabilities&.fs&.write_text_file
 
     call('fs/write_text_file', ACP::Types::WriteTextFileResponse, request)
   end
@@ -82,6 +82,29 @@ class ACP::AgentConnection::Client
     terminal_call('terminal/release', ACP::Types::ReleaseTerminalResponse, request)
   end
 
+  # @rbs request: ACP::Types::CreateElicitationRequest
+  # @rbs return: ACP::Types::CreateElicitationResponse | ACP::RequestError
+  def create_elicitation(request)
+    case request.mode
+    when ACP::Types::CreateElicitationRequest::Mode::Form
+      return ACP::RequestError.unadvertised('elicitation.form') unless capabilities&.elicitation&.form
+    when ACP::Types::CreateElicitationRequest::Mode::Url
+      return ACP::RequestError.unadvertised('elicitation.url') unless capabilities&.elicitation&.url
+    else
+      return ACP::RequestError.unadvertised("elicitation.#{request.mode['mode']}")
+    end
+
+    call('elicitation/create', ACP::Types::CreateElicitationResponse, request)
+  end
+
+  # @rbs notification: ACP::Types::CompleteElicitationNotification
+  # @rbs return: void
+  def complete_elicitation(notification)
+    return ACP::RequestError.unadvertised('elicitation.url') unless capabilities&.elicitation&.url
+
+    @peer.notify('elicitation/complete', notification.to_h)
+  end
+
   private
 
   # @rbs rpc_method: String
@@ -93,6 +116,8 @@ class ACP::AgentConnection::Client
     return result if result.is_a?(ACP::RequestError)
 
     type.from_h(result)
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_response(result)
   end
 
   # @rbs rpc_method: String
@@ -100,19 +125,8 @@ class ACP::AgentConnection::Client
   # @rbs request: ACP::AgentConnection::_Response
   # @rbs return: untyped
   def terminal_call(rpc_method, type, request)
-    return unadvertised('terminal') unless capabilities&.terminal
+    return ACP::RequestError.unadvertised('terminal') unless capabilities&.terminal
 
     call(rpc_method, type, request)
   end
-
-  # Same method-not-found code a peer would send, but with a message that says
-  # the refusal was local, so logs can tell the two cases apart.
-  #
-  # @rbs capability: String
-  # @rbs return: ACP::RequestError
-  def unadvertised(capability)
-    ACP::RequestError.new(
-      code: ACP::RequestError::METHOD_NOT_FOUND, message: "Client does not advertise #{capability}"
-    )
-  end
 end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ACP::AgentConnection::OptionalMethod::Logout
+  extend self
+
+  # @rbs return: String
+  def rpc_method
+    'logout'
+  end
+
+  # @rbs return: Symbol
+  def agent_method
+    :logout
+  end
+
+  # @rbs initialize_response: ACP::Types::InitializeResponse
+  # @rbs return: bool
+  def advertised?(initialize_response)
+    initialize_response.agent_capabilities&.auth&.logout ? true : false
+  end
+end

data/lib/acp/agent_connection.rb

@@ -2,8 +2,11 @@
 
 class ACP::AgentConnection
   # @rbs @transport: ACP::AgentConnection::_Transport
-  # @rbs @initialize_response: ACP::Types::InitializeResponse
+  # @rbs @capabilities: ACP::Types::AgentCapabilities
+  # @rbs @agent_info: ACP::Types::Implementation?
+  # @rbs @auth_methods: Array[ACP::Types::AuthMethod::t]
   # @rbs @factory: ^(ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent
+  # @rbs @logger: ACP::Transport::_Logger
 
   PROTOCOL_VERSION = 1 #: Integer
   OPTIONAL = [
@@ -12,7 +15,8 @@ class ACP::AgentConnection
     ACP::AgentConnection::OptionalMethod::Authenticate,
     ACP::AgentConnection::OptionalMethod::ResumeSession,
     ACP::AgentConnection::OptionalMethod::CloseSession,
-    ACP::AgentConnection::OptionalMethod::DeleteSession
+    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
@@ -26,16 +30,22 @@ class ACP::AgentConnection
   # @rbs capabilities: ACP::Types::AgentCapabilities
   # @rbs agent_info: ACP::Types::Implementation?
   # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
+  # @rbs logger: ACP::Transport::_Logger
   # @rbs &factory: (ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent
   # @rbs return: void
-  def initialize(transport:, capabilities:, agent_info: nil, auth_methods: [], &factory)
+  def initialize(
+    transport:,
+    capabilities:,
+    agent_info: nil,
+    auth_methods: [],
+    logger: ACP::Transport::StderrLogger.new,
+    &factory
+  )
     @transport = transport
-    @initialize_response = ACP::Types::InitializeResponse.new(
-      protocol_version: PROTOCOL_VERSION,
-      agent_capabilities: capabilities,
-      auth_methods:,
-      agent_info:
-    )
+    @logger = logger
+    @capabilities = capabilities
+    @agent_info = agent_info
+    @auth_methods = auth_methods
     @factory = factory
   end
 
@@ -43,7 +53,10 @@ class ACP::AgentConnection
   def start
     client = ACP::AgentConnection::Client.new(peer: @transport)
     agent = @factory.call(client)
-    advertised, unadvertised = OPTIONAL.partition { |method| method.advertised?(@initialize_response) }
+    # 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)) }
     missing = advertised.map(&:agent_method).reject { |name| agent.respond_to?(name) }
     raise ArgumentError, "initialize advertises methods the agent lacks: #{missing.join(', ')}" unless missing.empty?
 
@@ -70,6 +83,7 @@ class ACP::AgentConnection
       'session/resume' => route(ACP::Types::ResumeSessionRequest) { |request| full.resume_session(request) },
       'session/close' => route(ACP::Types::CloseSessionRequest) { |request| full.close_session(request) },
       'session/delete' => route(ACP::Types::DeleteSessionRequest) { |request| full.delete_session(request) },
+      'logout' => route(ACP::Types::LogoutRequest) { |request| full.logout(request) },
       'session/set_mode' => route(ACP::Types::SetSessionModeRequest) { |request| full.change_session_mode(request) },
       'session/set_config_option' => route(ACP::Types::SetSessionConfigOptionRequest) do |request|
         full.change_session_config_option(request)
@@ -80,7 +94,20 @@ class ACP::AgentConnection
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs return: Hash[String, ^(untyped) -> void]
   def notifications(agent)
-    { 'session/cancel' => ->(params) { agent.cancel(ACP::Types::CancelNotification.from_h(params)) } }
+    { 'session/cancel' => ->(params) { cancel(agent, params) } }
+  end
+
+  # A notification has no reply to carry a parse failure.
+  #
+  # @rbs agent: ACP::AgentConnection::_Agent
+  # @rbs params: untyped
+  # @rbs return: void
+  def cancel(agent, params)
+    notification = ACP::Types::CancelNotification.from_h(params)
+  rescue KeyError, TypeError, NoMethodError => e
+    @logger.warn("dropped malformed session/cancel: #{e.class}: #{e.message}")
+  else
+    agent.cancel(notification)
   end
 
   # Generated from_h raises on a missing key or a value of the wrong shape.
@@ -102,8 +129,34 @@ class ACP::AgentConnection
   # @rbs request: ACP::Types::InitializeRequest
   # @rbs return: ACP::Types::InitializeResponse
   def connect(client, request)
-    client.capabilities = request.client_capabilities || ACP::Types::ClientCapabilities.new
-    @initialize_response
+    capabilities = request.client_capabilities || ACP::Types::ClientCapabilities.new
+    client.capabilities = capabilities
+    initialize_response(auth_methods(capabilities))
+  end
+
+  # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
+  # @rbs return: ACP::Types::InitializeResponse
+  def initialize_response(auth_methods)
+    ACP::Types::InitializeResponse.new(
+      protocol_version: PROTOCOL_VERSION,
+      agent_capabilities: @capabilities,
+      auth_methods:,
+      agent_info: @agent_info
+    )
+  end
+
+  # @rbs capabilities: ACP::Types::ClientCapabilities
+  # @rbs return: Array[ACP::Types::AuthMethod::t]
+  def auth_methods(capabilities)
+    return @auth_methods if capabilities.auth&.terminal
+
+    @auth_methods.reject { |method| terminal_auth_method?(method) }
+  end
+
+  # @rbs method: ACP::Types::AuthMethod::t
+  # @rbs return: bool
+  def terminal_auth_method?(method)
+    method.is_a?(ACP::Types::AuthMethod::Terminal) || (method.is_a?(Hash) && method['type'] == 'terminal')
   end
 
   # session_created runs after the reply because the client must know the

data/lib/acp/client_connection.rb

@@ -3,28 +3,45 @@
 class ACP::ClientConnection
   # @rbs @transport: ACP::AgentConnection::_Transport
   # @rbs @permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs @read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?
+  # @rbs @write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?
   # @rbs @updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs @fs_capabilities: ACP::Types::FileSystemCapabilities?
   # @rbs @lock: Thread::Mutex
   # @rbs @streams: Hash[String, Thread::Queue]
+  # @rbs @logger: ACP::Transport::_Logger
+
+  PROTOCOL_VERSION = ACP::AgentConnection::PROTOCOL_VERSION #: Integer
 
   IGNORE = ->(_notification) {} #: ^(ACP::Types::SessionNotification) -> void
 
   # @rbs transport: ACP::AgentConnection::_Transport
   # @rbs permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?
+  # @rbs write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?
   # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs logger: ACP::Transport::_Logger
   # @rbs return: void
-  def initialize(transport:, permission:, updates: IGNORE)
+  def initialize(transport:, permission:, read_text_file: nil, write_text_file: nil, updates: IGNORE, logger: ACP::Transport::StderrLogger.new)
     @transport = transport
     @permission = permission
+    @read_text_file = read_text_file
+    @write_text_file = write_text_file
     @updates = updates
+    @fs_capabilities = nil
     @lock = Mutex.new
     @streams = {}
+    @logger = logger
   end
 
   # @rbs return: Thread
   def start
     @transport.start(
-      requests: { 'session/request_permission' => method(:request_permission) },
+      requests: {
+        'session/request_permission' => method(:request_permission),
+        'fs/read_text_file' => method(:read_text_file),
+        'fs/write_text_file' => method(:write_text_file)
+      },
       notifications: { 'session/update' => method(:dispatch) }
     )
   end
@@ -35,7 +52,23 @@ class ACP::ClientConnection
   # @rbs request: ACP::Types::InitializeRequest
   # @rbs return: ACP::Types::InitializeResponse | ACP::RequestError
   def connect(request)
-    parse(ACP::Types::InitializeResponse, @transport.request('initialize', request.to_h))
+    capabilities = request.client_capabilities&.fs
+    unserved = unserved_fs_methods(capabilities)
+    unless unserved.empty?
+      raise ArgumentError, "initialize advertises fs methods no handler serves: #{unserved.join(', ')}"
+    end
+
+    @fs_capabilities = capabilities
+    parse(ACP::Types::InitializeResponse, @transport.request('initialize', request.to_h)).then do |response|
+      next response if response.is_a?(ACP::RequestError)
+
+      next response if response.protocol_version == PROTOCOL_VERSION
+
+      ACP::RequestError.unsupported_protocol_version(
+        requested: request.protocol_version,
+        returned: response.protocol_version
+      )
+    end
   end
 
   # @rbs request: ACP::Types::NewSessionRequest
@@ -64,12 +97,60 @@ class ACP::ClientConnection
     parse(ACP::Types::ListSessionsResponse, @transport.request('session/list', request.to_h))
   end
 
+  # The agent does not replay history on resume, so unlike session_load there
+  # is nothing to stream and no block is taken.
+  #
+  # @rbs request: ACP::Types::ResumeSessionRequest
+  # @rbs return: ACP::Types::ResumeSessionResponse | ACP::RequestError
+  def session_resume(request)
+    parse(ACP::Types::ResumeSessionResponse, @transport.request('session/resume', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::CloseSessionRequest
+  # @rbs return: ACP::Types::CloseSessionResponse | ACP::RequestError
+  def session_close(request)
+    parse(ACP::Types::CloseSessionResponse, @transport.request('session/close', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::DeleteSessionRequest
+  # @rbs return: ACP::Types::DeleteSessionResponse | ACP::RequestError
+  def session_delete(request)
+    parse(ACP::Types::DeleteSessionResponse, @transport.request('session/delete', request.to_h))
+  end
+
   # @rbs notification: ACP::Types::CancelNotification
   # @rbs return: void
   def session_cancel(notification)
     @transport.notify('session/cancel', notification.to_h)
   end
 
+  # @rbs request: ACP::Types::SetSessionModeRequest
+  # @rbs return: ACP::Types::SetSessionModeResponse | ACP::RequestError
+  def session_set_mode(request)
+    parse(ACP::Types::SetSessionModeResponse, @transport.request('session/set_mode', request.to_h))
+  end
+
+  # The reply carries the session's complete option list, so it replaces any
+  # state held from an earlier reply rather than merging into it.
+  #
+  # @rbs request: ACP::Types::SetSessionConfigOptionRequest
+  # @rbs return: ACP::Types::SetSessionConfigOptionResponse | ACP::RequestError
+  def session_set_config_option(request)
+    parse(ACP::Types::SetSessionConfigOptionResponse, @transport.request('session/set_config_option', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::AuthenticateRequest
+  # @rbs return: ACP::Types::AuthenticateResponse | ACP::RequestError
+  def authenticate(request)
+    parse(ACP::Types::AuthenticateResponse, @transport.request('authenticate', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::LogoutRequest
+  # @rbs return: ACP::Types::LogoutResponse | ACP::RequestError
+  def logout(request)
+    parse(ACP::Types::LogoutResponse, @transport.request('logout', request.to_h))
+  end
+
   private
 
   # @rbs type: ACP::AgentConnection::_Parser
@@ -79,6 +160,8 @@ class ACP::ClientConnection
     return result if result.is_a?(ACP::RequestError)
 
     type.from_h(result)
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_response(result)
   end
 
   # The request waits on its own thread so the caller's thread can yield each
@@ -92,7 +175,21 @@ class ACP::ClientConnection
   # @rbs return: (Hash[String, untyped] | ACP::RequestError)
   def stream(session_id, method, params)
     queue = Thread::Queue.new
-    @lock.synchronize { @streams[session_id] = queue }
+    # The check and the insert share one lock acquisition so a concurrent
+    # stream cannot register between them.
+    claimed = @lock.synchronize do
+      if @streams.key?(session_id)
+        false
+      else
+        @streams[session_id] = queue
+        true
+      end
+    end
+    unless claimed
+      return ACP::RequestError.new(
+        code: ACP::RequestError::INVALID_REQUEST, message: "A stream is already open for session #{session_id}"
+      )
+    end
     requester = Thread.new do
       @transport.request(method, params)
     ensure
@@ -105,12 +202,16 @@ class ACP::ClientConnection
   end
 
   # Pushes under the lock so a stream cannot close its queue between the
-  # lookup and the push.
+  # lookup and the push. A malformed notification has no reply to carry the
+  # failure.
   #
   # @rbs params: untyped
   # @rbs return: void
   def dispatch(params)
     notification = ACP::Types::SessionNotification.from_h(params)
+  rescue KeyError, TypeError, NoMethodError => e
+    @logger.warn("dropped malformed session/update: #{e.class}: #{e.message}")
+  else
     queue = @lock.synchronize { @streams[notification.session_id]&.push(notification.update) }
     @updates.call(notification) unless queue
   end
@@ -124,4 +225,46 @@ class ACP::ClientConnection
   else
     @permission.call(request)
   end
+
+  # The routes are registered at start, before connect records the advertised
+  # capabilities, so each one answers -32601 until then.
+  #
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::ReadTextFileResponse | ACP::RequestError)
+  def read_text_file(params)
+    return ACP::RequestError.unadvertised('fs.readTextFile') unless @fs_capabilities&.read_text_file
+
+    request = ACP::Types::ReadTextFileRequest.from_h(params)
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_params
+  else
+    # Safe: connect refuses an advertised capability no handler serves.
+    handler = @read_text_file #: ^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
+    handler.call(request)
+  end
+
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::WriteTextFileResponse | ACP::RequestError)
+  def write_text_file(params)
+    return ACP::RequestError.unadvertised('fs.writeTextFile') unless @fs_capabilities&.write_text_file
+
+    request = ACP::Types::WriteTextFileRequest.from_h(params)
+  rescue KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_params
+  else
+    # Safe: connect refuses an advertised capability no handler serves.
+    handler = @write_text_file #: ^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError)
+    handler.call(request)
+  end
+
+  # The fs capabilities initialize advertises that no injected handler serves.
+  #
+  # @rbs capabilities: ACP::Types::FileSystemCapabilities?
+  # @rbs return: Array[String]
+  def unserved_fs_methods(capabilities)
+    {
+      'fs.readTextFile' => capabilities&.read_text_file && !@read_text_file,
+      'fs.writeTextFile' => capabilities&.write_text_file && !@write_text_file
+    }.select { |_, unserved| unserved }.keys
+  end
 end

data/lib/acp/request_error.rb

@@ -58,11 +58,41 @@ class ACP::RequestError
     new(code: INVALID_PARAMS, message: 'Invalid params')
   end
 
+  # The method-not-found code for a method the client's capabilities do not
+  # advertise, with a message that names the capability so it can be told
+  # apart from an unknown method.
+  #
+  # @rbs capability: String
+  # @rbs return: ACP::RequestError
+  def self.unadvertised(capability)
+    new(code: METHOD_NOT_FOUND, message: "Client does not advertise #{capability}")
+  end
+
   # @rbs return: ACP::RequestError
   def self.internal_error
     new(code: INTERNAL_ERROR, message: 'Internal error')
   end
 
+  # The message tells a malformed peer reply apart from an internal error a
+  # handler raised, though both use the -32603 code.
+  #
+  # @rbs response: untyped
+  # @rbs return: ACP::RequestError
+  def self.invalid_response(response)
+    new(code: INTERNAL_ERROR, message: 'Invalid response', data: response)
+  end
+
+  # A local refusal of an initialize reply that names a version the SDK does
+  # not speak; the message names both versions so logs can tell it from a
+  # peer's error.
+  #
+  # @rbs requested: Integer
+  # @rbs returned: Integer
+  # @rbs return: ACP::RequestError
+  def self.unsupported_protocol_version(requested:, returned:)
+    new(code: INTERNAL_ERROR, message: "Unsupported protocol version: requested #{requested}, returned #{returned}")
+  end
+
   # @rbs return: ACP::RequestError
   def self.request_cancelled
     new(code: REQUEST_CANCELLED, message: 'Request cancelled')

data/lib/acp/transport/stderr_logger.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# The default sink for dropped messages and swallowed errors: the spec
+# sanctions agents logging to stderr.
+class ACP::Transport::StderrLogger
+  # @rbs message: String
+  # @rbs return: void
+  def warn(message)
+    Kernel.warn("acp: WARN: #{message}")
+  end
+
+  # @rbs message: String
+  # @rbs return: void
+  def error(message)
+    Kernel.warn("acp: ERROR: #{message}")
+  end
+end