acp-sdk 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0121ff621c45deb5578a15051611ea98d8d174193528c3df214fe4e036561ff
-  data.tar.gz: e26701095772e5bbf41a18a8e2bc9f4ac9609657aae1dee7c82891de6cf5b48c
+  metadata.gz: 367678f3b99c82b2f768879be0308249d9b32ce8ce94c3d4e6de6c12c4a1c043
+  data.tar.gz: 071e457b8e00fa19be760fff65cfd69998102e54b4b3d47f9b3cc0d80c359fc3
 SHA512:
-  metadata.gz: 66f390b3cf58c661064fe12ca5c7bbf04f560a81187f8cd37cce6d820870eb9f83717b655d04305a9a926e3cc08af618c1956acb7c2425899d2d3238e05d2651
-  data.tar.gz: 13853bc47c5c15a249296d9418fb951f52d512fea28f92fe9bf601c1a3e43d98840cbbbbfc181ff53150572db0393388553bf27f3c1746ca135f0467905d4270
+  metadata.gz: 706206bd29062ef6ecf1856b9e9671113e02bb6eb6ac837c2815bfcdbbff4bc07ac8d2c6394ec6f7b33c37a3832a9e0c4bb5c4e5c4699c1cdc129e875f693605
+  data.tar.gz: 5a73a945d099dedcf5837aa1c897b1dca0313a49d131337756b26c28731ddedb14b96c21722c7d6ecff3a21e6bed811e036551724c12bebcdf53f88a56121f8e

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.6.0](https://github.com/bottrall/acp-sdk/compare/v0.5.0...v0.6.0) (2026-10-04)
+
+
+### Features
+
+* answer pending permission requests with cancelled after session_cancel ([#70](https://github.com/bottrall/acp-sdk/issues/70)) ([06a218b](https://github.com/bottrall/acp-sdk/commit/06a218b6262ff409e301d08a43330af5b60837e0))
+* extension methods on both connections ([#72](https://github.com/bottrall/acp-sdk/issues/72)) ([d1faa1a](https://github.com/bottrall/acp-sdk/commit/d1faa1a738019e73a4dbad5b59f480795f8dd4bf))
+
+## [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)
 
 

data/README.md

@@ -55,12 +55,15 @@ The agent's contract:
 - `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`.
+Extensions are `_`-prefixed methods outside the spec. `AgentConnection` takes `extension_requests` and `extension_notifications` hashes keyed by the raw wire name, and `client.ext_request` and `client.ext_notify` send them to the client; a handler name without the `_` prefix raises `ArgumentError`, and an extension request with no handler is answered with `-32601`.
+
+[`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 +93,20 @@ 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.
+
+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`.
 
 ## 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,49 @@ 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
+
+  # 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 method: String
+  # @rbs params: untyped
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  def ext_request(method, params = nil)
+    ACP::Extensions.validate_name(method)
+    @peer.request(method, params)
+  end
+
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: void
+  def ext_notify(method, params = nil)
+    ACP::Extensions.validate_name(method)
+    @peer.notify(method, params)
+  end
+
   private
 
   # @rbs rpc_method: String
@@ -102,19 +145,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.rb

@@ -2,8 +2,13 @@
 
 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 @extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
+  # @rbs @logger: ACP::Transport::_Logger
 
   PROTOCOL_VERSION = 1 #: Integer
   OPTIONAL = [
@@ -27,16 +32,30 @@ class ACP::AgentConnection
   # @rbs capabilities: ACP::Types::AgentCapabilities
   # @rbs agent_info: ACP::Types::Implementation?
   # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
+  # @rbs extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
+  # @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: [],
+    extension_requests: {},
+    extension_notifications: {},
+    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
+    @extension_requests = extension_requests
+    @extension_notifications = extension_notifications
+    extension_requests.each_key { |name| ACP::Extensions.validate_name(name) }
+    extension_notifications.each_key { |name| ACP::Extensions.validate_name(name) }
     @factory = factory
   end
 
@@ -44,12 +63,18 @@ 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?
 
     unrouted = unadvertised.map(&:rpc_method) + PER_SESSION.reject { |_, name| agent.respond_to?(name) }.keys
-    @transport.start(requests: requests(agent, client).except(*unrouted), notifications: notifications(agent))
+    @transport.start(
+      requests: requests(agent, client).except(*unrouted).merge(@extension_requests),
+      notifications: notifications(agent).merge(@extension_notifications)
+    )
   end
 
   private
@@ -82,7 +107,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.
@@ -104,8 +142,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,29 +3,69 @@
 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 @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 @logger: ACP::Transport::_Logger
+
+  PROTOCOL_VERSION = ACP::AgentConnection::PROTOCOL_VERSION #: Integer
 
   IGNORE = ->(_notification) {} #: ^(ACP::Types::SessionNotification) -> void
 
+  CANCELLED = ACP::Types::RequestPermissionResponse.new(
+    outcome: ACP::Types::RequestPermissionOutcome::Cancelled.new
+  ) #: ACP::Types::RequestPermissionResponse
+
   # @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 extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
+  # @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,
+    extension_requests: {},
+    extension_notifications: {},
+    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
+    @extension_requests = extension_requests
+    @extension_notifications = extension_notifications
+    extension_requests.each_key { |name| ACP::Extensions.validate_name(name) }
+    extension_notifications.each_key { |name| ACP::Extensions.validate_name(name) }
     @lock = Mutex.new
     @streams = {}
+    @pending_permissions = {}
+    @logger = logger
   end
 
   # @rbs return: Thread
   def start
     @transport.start(
-      requests: { 'session/request_permission' => method(:request_permission) },
-      notifications: { 'session/update' => method(:dispatch) }
+      requests: {
+        'session/request_permission' => method(:request_permission),
+        'fs/read_text_file' => method(:read_text_file),
+        'fs/write_text_file' => method(:write_text_file)
+      }.merge(@extension_requests),
+      notifications: { 'session/update' => method(:dispatch) }.merge(@extension_notifications)
     )
   end
 
@@ -35,7 +75,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,10 +120,85 @@ 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
+
+  # The spec requires a pending session/request_permission to be answered with
+  # the cancelled outcome once the turn is cancelled, so every queue registered
+  # for the session gets one before this returns. The notification goes first
+  # so the wire order is cancel, then the cancelled replies.
+  #
   # @rbs notification: ACP::Types::CancelNotification
   # @rbs return: void
   def session_cancel(notification)
     @transport.notify('session/cancel', notification.to_h)
+    pending = @lock.synchronize { @pending_permissions.delete(notification.session_id) }
+    pending&.each { |replies| replies << [:value, CANCELLED] }
+  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
+
+  # Sends an extension request, keyed by its raw `_`-prefixed wire name, and
+  # returns the agent's reply as-is: extension methods have no schema to
+  # parse the result into.
+  #
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  def ext_request(method, params = nil)
+    ACP::Extensions.validate_name(method)
+    @transport.request(method, params)
+  end
+
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: void
+  def ext_notify(method, params = nil)
+    ACP::Extensions.validate_name(method)
+    @transport.notify(method, params)
   end
 
   private
@@ -94,7 +225,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
@@ -107,16 +252,24 @@ 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
 
+  # The handler runs on its own thread so a cancelled request is answered
+  # without waiting for it, and whatever it returns after that is pushed to a
+  # queue nobody reads.
+  #
   # @rbs params: untyped
   # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
   def request_permission(params)
@@ -124,6 +277,86 @@ class ACP::ClientConnection
   rescue KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_params
   else
-    @permission.call(request)
+    replies = Thread::Queue.new
+    register_permission(request.session_id, replies)
+    Thread.new do
+      # A raised StandardError is not a returned ACP::RequestError, so the two
+      # need distinct shapes on the queue.
+      replies << begin
+        [:value, @permission.call(request)]
+      rescue StandardError => e
+        [:raised, e]
+      end
+    ensure
+      unregister_permission(request.session_id, replies)
+    end
+    settled = replies.pop
+    # Re-raised so the transport's invoke turns it into an error reply, as it
+    # would if the handler ran on the serve thread itself.
+    raise settled[1] if settled[0] == :raise
+
+    settled[1]
+  end
+
+  # @rbs session_id: String
+  # @rbs replies: Thread::Queue
+  # @rbs return: void
+  def register_permission(session_id, replies)
+    @lock.synchronize { (@pending_permissions[session_id] ||= []) << replies }
+  end
+
+  # @rbs session_id: String
+  # @rbs replies: Thread::Queue
+  # @rbs return: void
+  def unregister_permission(session_id, replies)
+    @lock.synchronize do
+      pending = @pending_permissions[session_id]
+      if pending
+        pending.delete(replies)
+        @pending_permissions.delete(session_id) if pending.empty?
+      end
+    end
+  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/extensions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Shared by the connections' handler maps and send paths, so a plain method
+# name cannot slip into the extension routes.
+module ACP::Extensions
+  extend self
+
+  # @rbs name: String
+  # @rbs return: void
+  def validate_name(name)
+    return if name.start_with?('_')
+
+    raise ArgumentError, "extension method names must start with '_' (got #{name.inspect})"
+  end
+end

data/lib/acp/request_error.rb

@@ -58,6 +58,16 @@ 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')
@@ -72,6 +82,17 @@ class ACP::RequestError
     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

data/lib/acp/transport/stdio.rb

@@ -15,6 +15,7 @@ class ACP::Transport::Stdio
   # @rbs @pending: Hash[untyped, Thread::Queue]
   # @rbs @next_id: Integer
   # @rbs @closed: bool
+  # @rbs @logger: ACP::Transport::_Logger
 
   CONNECTION_CLOSED = ACP::RequestError.new(
     code: ACP::RequestError::INTERNAL_ERROR, message: 'Connection closed'
@@ -22,8 +23,9 @@ class ACP::Transport::Stdio
 
   # @rbs input: _Reader
   # @rbs output: _Writer
+  # @rbs logger: ACP::Transport::_Logger
   # @rbs return: void
-  def initialize(input:, output:)
+  def initialize(input:, output:, logger: ACP::Transport::StderrLogger.new)
     @input = input
     @output = output
     @write_lock = Mutex.new
@@ -31,6 +33,7 @@ class ACP::Transport::Stdio
     @pending = {}
     @next_id = 0
     @closed = false
+    @logger = logger
   end
 
   # Returns the reader thread, which ends at EOF on input after releasing any
@@ -94,7 +97,7 @@ class ACP::Transport::Stdio
       # Run on the reader thread so notifications (session/update) keep their
       # order; a JSON-RPC notification has no reply to carry a handler error.
       handler = notifications[method]
-      quietly { handler.call(message['params']) } if handler
+      quietly('notification handler') { handler.call(message['params']) } if handler
     elsif message.key?('result')
       settle(message['id'], message['result'])
     elsif error.is_a?(Hash) && error['code'].is_a?(Integer) && error['message'].is_a?(String)
@@ -126,7 +129,7 @@ class ACP::Transport::Stdio
       case outcome
       when ACP::Transport::Reply
         reply(id, outcome.result)
-        quietly(&outcome.after)
+        quietly('reply after callback', &outcome.after)
       else reply(id, outcome)
       end
     end
@@ -136,12 +139,13 @@ class ACP::Transport::Stdio
   # Reply's after once the reply is on the wire. An exception must not kill
   # the reader thread or print a thread report.
   #
+  # @rbs label: String
   # @rbs &block: () -> void
   # @rbs return: void
-  def quietly
+  def quietly(label)
     yield
-  rescue StandardError
-    nil
+  rescue StandardError => e
+    @logger.error("#{label} raised #{e.class}: #{e.message}")
   end
 
   # Handlers are application code at the protocol boundary: an exception
@@ -198,6 +202,9 @@ class ACP::Transport::Stdio
     end
   end
 
+  # A closed peer must not kill the thread writing the reply: the reader has
+  # to keep draining input so pending requests still settle at EOF.
+  #
   # @rbs message: Hash[String, untyped]
   # @rbs return: void
   def write(message)
@@ -206,5 +213,7 @@ class ACP::Transport::Stdio
       @output.write(line)
       @output.flush
     end
+  rescue Errno::EPIPE => e
+    @logger.warn("write to closed peer: #{e.class}: #{e.message}")
   end
 end

data/lib/acp/version.rb

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

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

@@ -55,6 +55,28 @@ class ACP::AgentConnection::Client
   # @rbs return: ACP::Types::ReleaseTerminalResponse | ACP::RequestError
   def release_terminal: (ACP::Types::ReleaseTerminalRequest request) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
 
+  # @rbs request: ACP::Types::CreateElicitationRequest
+  # @rbs return: ACP::Types::CreateElicitationResponse | ACP::RequestError
+  def create_elicitation: (ACP::Types::CreateElicitationRequest request) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError)
+
+  # @rbs notification: ACP::Types::CompleteElicitationNotification
+  # @rbs return: void
+  def complete_elicitation: (ACP::Types::CompleteElicitationNotification notification) -> void
+
+  # 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 method: String
+  # @rbs params: untyped
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  def ext_request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
+
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: void
+  def ext_notify: (String method, ?untyped params) -> void
+
   private
 
   # @rbs rpc_method: String
@@ -68,11 +90,4 @@ class ACP::AgentConnection::Client
   # @rbs request: ACP::AgentConnection::_Response
   # @rbs return: untyped
   def terminal_call: (String rpc_method, ACP::AgentConnection::_Parser type, ACP::AgentConnection::_Response request) -> untyped
-
-  # 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: (String capability) -> ACP::RequestError
 end

data/sig/generated/acp/agent_connection.rbs

@@ -1,12 +1,22 @@
 # Generated from lib/acp/agent_connection.rb with RBS::Inline
 
 class ACP::AgentConnection
-  @transport: ACP::AgentConnection::_Transport
+  @logger: ACP::Transport::_Logger
+
+  @extension_notifications: Hash[String, ^(untyped) -> void]
 
-  @initialize_response: ACP::Types::InitializeResponse
+  @extension_requests: Hash[String, ^(untyped) -> untyped]
 
   @factory: ^(ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent
 
+  @auth_methods: Array[ACP::Types::AuthMethod::t]
+
+  @agent_info: ACP::Types::Implementation?
+
+  @capabilities: ACP::Types::AgentCapabilities
+
+  @transport: ACP::AgentConnection::_Transport
+
   PROTOCOL_VERSION: Integer
 
   OPTIONAL: Array[ACP::AgentConnection::_OptionalMethod]
@@ -20,9 +30,12 @@ class ACP::AgentConnection
   # @rbs capabilities: ACP::Types::AgentCapabilities
   # @rbs agent_info: ACP::Types::Implementation?
   # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
+  # @rbs extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
+  # @rbs logger: ACP::Transport::_Logger
   # @rbs &factory: (ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent
   # @rbs return: void
-  def initialize: (transport: ACP::AgentConnection::_Transport, capabilities: ACP::Types::AgentCapabilities, ?agent_info: ACP::Types::Implementation?, ?auth_methods: Array[ACP::Types::AuthMethod::t]) { (ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent } -> void
+  def initialize: (transport: ACP::AgentConnection::_Transport, capabilities: ACP::Types::AgentCapabilities, ?agent_info: ACP::Types::Implementation?, ?auth_methods: Array[ACP::Types::AuthMethod::t], ?extension_requests: Hash[String, ^(untyped) -> untyped], ?extension_notifications: Hash[String, ^(untyped) -> void], ?logger: ACP::Transport::_Logger) { (ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent } -> void
 
   # @rbs return: Thread
   def start: () -> Thread
@@ -38,6 +51,13 @@ class ACP::AgentConnection
   # @rbs return: Hash[String, ^(untyped) -> void]
   def notifications: (ACP::AgentConnection::_Agent agent) -> Hash[String, ^(untyped) -> void]
 
+  # A notification has no reply to carry a parse failure.
+  #
+  # @rbs agent: ACP::AgentConnection::_Agent
+  # @rbs params: untyped
+  # @rbs return: void
+  def cancel: (ACP::AgentConnection::_Agent agent, untyped params) -> void
+
   # Generated from_h raises on a missing key or a value of the wrong shape.
   #
   # @rbs type: ACP::AgentConnection::_Parser
@@ -50,6 +70,18 @@ class ACP::AgentConnection
   # @rbs return: ACP::Types::InitializeResponse
   def connect: (ACP::AgentConnection::Client client, ACP::Types::InitializeRequest request) -> ACP::Types::InitializeResponse
 
+  # @rbs auth_methods: Array[ACP::Types::AuthMethod::t]
+  # @rbs return: ACP::Types::InitializeResponse
+  def initialize_response: (Array[ACP::Types::AuthMethod::t] auth_methods) -> ACP::Types::InitializeResponse
+
+  # @rbs capabilities: ACP::Types::ClientCapabilities
+  # @rbs return: Array[ACP::Types::AuthMethod::t]
+  def auth_methods: (ACP::Types::ClientCapabilities capabilities) -> Array[ACP::Types::AuthMethod::t]
+
+  # @rbs method: ACP::Types::AuthMethod::t
+  # @rbs return: bool
+  def terminal_auth_method?: (ACP::Types::AuthMethod::t method) -> bool
+
   # session_created runs after the reply because the client must know the
   # session id before updates for it (e.g. available commands) arrive.
   #

data/sig/generated/acp/client_connection.rbs

@@ -1,23 +1,46 @@
 # Generated from lib/acp/client_connection.rb with RBS::Inline
 
 class ACP::ClientConnection
+  @logger: ACP::Transport::_Logger
+
+  @pending_permissions: Hash[String, Array[Thread::Queue]]
+
   @streams: Hash[String, Thread::Queue]
 
   @lock: Thread::Mutex
 
+  @extension_notifications: Hash[String, ^(untyped) -> void]
+
+  @extension_requests: Hash[String, ^(untyped) -> untyped]
+
+  @fs_capabilities: ACP::Types::FileSystemCapabilities?
+
   @updates: ACP::ClientConnection::_UpdateHandler
 
+  @write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?
+
+  @read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?
+
   @permission: ACP::ClientConnection::_PermissionHandler
 
   @transport: ACP::AgentConnection::_Transport
 
+  PROTOCOL_VERSION: Integer
+
   IGNORE: ^(ACP::Types::SessionNotification) -> void
 
+  CANCELLED: ACP::Types::RequestPermissionResponse
+
   # @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 extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
+  # @rbs logger: ACP::Transport::_Logger
   # @rbs return: void
-  def initialize: (transport: ACP::AgentConnection::_Transport, permission: ACP::ClientConnection::_PermissionHandler, ?updates: ACP::ClientConnection::_UpdateHandler) -> void
+  def initialize: (transport: ACP::AgentConnection::_Transport, permission: ACP::ClientConnection::_PermissionHandler, ?read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?, ?write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?, ?updates: ACP::ClientConnection::_UpdateHandler, ?extension_requests: Hash[String, ^(untyped) -> untyped], ?extension_notifications: Hash[String, ^(untyped) -> void], ?logger: ACP::Transport::_Logger) -> void
 
   # @rbs return: Thread
   def start: () -> Thread
@@ -47,10 +70,63 @@ class ACP::ClientConnection
   # @rbs return: ACP::Types::ListSessionsResponse | ACP::RequestError
   def session_list: (ACP::Types::ListSessionsRequest request) -> (ACP::Types::ListSessionsResponse | ACP::RequestError)
 
+  # 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: (ACP::Types::ResumeSessionRequest request) -> (ACP::Types::ResumeSessionResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::CloseSessionRequest
+  # @rbs return: ACP::Types::CloseSessionResponse | ACP::RequestError
+  def session_close: (ACP::Types::CloseSessionRequest request) -> (ACP::Types::CloseSessionResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::DeleteSessionRequest
+  # @rbs return: ACP::Types::DeleteSessionResponse | ACP::RequestError
+  def session_delete: (ACP::Types::DeleteSessionRequest request) -> (ACP::Types::DeleteSessionResponse | ACP::RequestError)
+
+  # The spec requires a pending session/request_permission to be answered with
+  # the cancelled outcome once the turn is cancelled, so every queue registered
+  # for the session gets one before this returns. The notification goes first
+  # so the wire order is cancel, then the cancelled replies.
+  #
   # @rbs notification: ACP::Types::CancelNotification
   # @rbs return: void
   def session_cancel: (ACP::Types::CancelNotification notification) -> void
 
+  # @rbs request: ACP::Types::SetSessionModeRequest
+  # @rbs return: ACP::Types::SetSessionModeResponse | ACP::RequestError
+  def session_set_mode: (ACP::Types::SetSessionModeRequest request) -> (ACP::Types::SetSessionModeResponse | ACP::RequestError)
+
+  # 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: (ACP::Types::SetSessionConfigOptionRequest request) -> (ACP::Types::SetSessionConfigOptionResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::AuthenticateRequest
+  # @rbs return: ACP::Types::AuthenticateResponse | ACP::RequestError
+  def authenticate: (ACP::Types::AuthenticateRequest request) -> (ACP::Types::AuthenticateResponse | ACP::RequestError)
+
+  # @rbs request: ACP::Types::LogoutRequest
+  # @rbs return: ACP::Types::LogoutResponse | ACP::RequestError
+  def logout: (ACP::Types::LogoutRequest request) -> (ACP::Types::LogoutResponse | ACP::RequestError)
+
+  # Sends an extension request, keyed by its raw `_`-prefixed wire name, and
+  # returns the agent's reply as-is: extension methods have no schema to
+  # parse the result into.
+  #
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  def ext_request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
+
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: void
+  def ext_notify: (String method, ?untyped params) -> void
+
   private
 
   # @rbs type: ACP::AgentConnection::_Parser
@@ -70,13 +146,45 @@ class ACP::ClientConnection
   def stream: (String session_id, String method, Hash[String, untyped] params) { (ACP::Types::SessionUpdate::t) -> void } -> (Hash[String, untyped] | ACP::RequestError)
 
   # 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: (untyped params) -> void
 
+  # The handler runs on its own thread so a cancelled request is answered
+  # without waiting for it, and whatever it returns after that is pushed to a
+  # queue nobody reads.
+  #
   # @rbs params: untyped
   # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
   def request_permission: (untyped params) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
+
+  # @rbs session_id: String
+  # @rbs replies: Thread::Queue
+  # @rbs return: void
+  def register_permission: (String session_id, Thread::Queue replies) -> void
+
+  # @rbs session_id: String
+  # @rbs replies: Thread::Queue
+  # @rbs return: void
+  def unregister_permission: (String session_id, Thread::Queue replies) -> void
+
+  # 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: (untyped params) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
+
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::WriteTextFileResponse | ACP::RequestError)
+  def write_text_file: (untyped params) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError)
+
+  # The fs capabilities initialize advertises that no injected handler serves.
+  #
+  # @rbs capabilities: ACP::Types::FileSystemCapabilities?
+  # @rbs return: Array[String]
+  def unserved_fs_methods: (ACP::Types::FileSystemCapabilities? capabilities) -> Array[String]
 end

data/sig/generated/acp/extensions.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/acp/extensions.rb with RBS::Inline
+
+# Shared by the connections' handler maps and send paths, so a plain method
+# name cannot slip into the extension routes.
+module ACP::Extensions
+  # @rbs name: String
+  # @rbs return: void
+  def validate_name: (String name) -> void
+end

data/sig/generated/acp/request_error.rbs

@@ -50,6 +50,14 @@ class ACP::RequestError
   # @rbs return: ACP::RequestError
   def self.invalid_params: () -> ACP::RequestError
 
+  # 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: (String capability) -> ACP::RequestError
+
   # @rbs return: ACP::RequestError
   def self.internal_error: () -> ACP::RequestError
 
@@ -60,6 +68,15 @@ class ACP::RequestError
   # @rbs return: ACP::RequestError
   def self.invalid_response: (untyped response) -> ACP::RequestError
 
+  # 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: Integer, returned: Integer) -> ACP::RequestError
+
   # @rbs return: ACP::RequestError
   def self.request_cancelled: () -> ACP::RequestError
 

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

@@ -0,0 +1,13 @@
+# Generated from lib/acp/transport/stderr_logger.rb with RBS::Inline
+
+# 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: (String message) -> void
+
+  # @rbs message: String
+  # @rbs return: void
+  def error: (String message) -> void
+end

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

@@ -6,6 +6,8 @@
 # outbound request mid-turn and still see notifications (e.g. session/cancel)
 # that arrive meanwhile.
 class ACP::Transport::Stdio
+  @logger: ACP::Transport::_Logger
+
   @closed: bool
 
   @next_id: Integer
@@ -24,8 +26,9 @@ class ACP::Transport::Stdio
 
   # @rbs input: _Reader
   # @rbs output: _Writer
+  # @rbs logger: ACP::Transport::_Logger
   # @rbs return: void
-  def initialize: (input: _Reader, output: _Writer) -> void
+  def initialize: (input: _Reader, output: _Writer, ?logger: ACP::Transport::_Logger) -> void
 
   # Returns the reader thread, which ends at EOF on input after releasing any
   # pending outbound requests.
@@ -73,9 +76,10 @@ class ACP::Transport::Stdio
   # Reply's after once the reply is on the wire. An exception must not kill
   # the reader thread or print a thread report.
   #
+  # @rbs label: String
   # @rbs &block: () -> void
   # @rbs return: void
-  def quietly: () { () -> void } -> void
+  def quietly: (String label) { () -> void } -> void
 
   # Handlers are application code at the protocol boundary: an exception
   # becomes an error response instead of killing the thread serving it.
@@ -105,6 +109,9 @@ class ACP::Transport::Stdio
   # @rbs return: void
   def close: () -> void
 
+  # A closed peer must not kill the thread writing the reply: the reader has
+  # to keep draining input so pending requests still settle at EOF.
+  #
   # @rbs message: Hash[String, untyped]
   # @rbs return: void
   def write: (Hash[String, untyped] message) -> void

data/sig/manual/acp/agent_connection.rbs

@@ -79,6 +79,10 @@ class ACP::AgentConnection
     def wait_for_terminal_exit: (ACP::Types::WaitForTerminalExitRequest) -> (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError)
     def kill_terminal: (ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError)
     def release_terminal: (ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
+    def create_elicitation: (ACP::Types::CreateElicitationRequest request) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError)
+    def complete_elicitation: (ACP::Types::CompleteElicitationNotification notification) -> void
+    def ext_request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
+    def ext_notify: (String method, ?untyped params) -> void
     def capabilities: () -> ACP::Types::ClientCapabilities?
   end
 

data/sig/manual/acp/extensions.rbs

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

data/sig/manual/acp/transport.rbs

@@ -0,0 +1,8 @@
+module ACP::Transport
+  # Receives the reports the SDK logs for dropped messages and swallowed
+  # errors; a log message is a single line with no trailing newline.
+  interface _Logger
+    def warn: (String message) -> void
+    def error: (String message) -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -44,10 +44,12 @@ files:
 - lib/acp/agent_connection/optional_method/resume_session.rb
 - lib/acp/agent_process.rb
 - lib/acp/client_connection.rb
+- lib/acp/extensions.rb
 - lib/acp/request_error.rb
 - lib/acp/sdk.rb
 - lib/acp/transport.rb
 - lib/acp/transport/reply.rb
+- lib/acp/transport/stderr_logger.rb
 - lib/acp/transport/stdio.rb
 - lib/acp/types.rb
 - lib/acp/types/agent_auth_capabilities.rb
@@ -258,10 +260,12 @@ files:
 - sig/generated/acp/agent_connection/optional_method/resume_session.rbs
 - sig/generated/acp/agent_process.rbs
 - sig/generated/acp/client_connection.rbs
+- sig/generated/acp/extensions.rbs
 - sig/generated/acp/request_error.rbs
 - sig/generated/acp/sdk.rbs
 - sig/generated/acp/transport.rbs
 - sig/generated/acp/transport/reply.rbs
+- sig/generated/acp/transport/stderr_logger.rbs
 - sig/generated/acp/transport/stdio.rbs
 - sig/generated/acp/types.rbs
 - sig/generated/acp/types/agent_auth_capabilities.rbs
@@ -470,6 +474,8 @@ files:
 - sig/manual/acp/agent_connection/optional_method/resume_session.rbs
 - sig/manual/acp/agent_process.rbs
 - sig/manual/acp/client_connection.rbs
+- sig/manual/acp/extensions.rbs
+- sig/manual/acp/transport.rbs
 - sig/manual/acp/transport/stdio.rbs
 homepage: https://github.com/bottrall/acp-sdk
 licenses: