acp-sdk 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ee3b18dbb3a538b575c1b3309f93bd84eab3566e4491d39646dde8f0114ff6
-  data.tar.gz: ef1b3bed3a05dea92f076f4ed67e8378a3893d522db9ffe76ad445810b5fb20e
+  metadata.gz: 59dca9a568751a3b4c29c1ff4afdd9ad12e997689d5eb3a4782f2a4c5ced81b0
+  data.tar.gz: 99bde6bbc81d16012a6d9b3654bf15f15a35a40713f3d6dbbe686557f182ac50
 SHA512:
-  metadata.gz: 69232d2be95232917e3f3c25c0eb890cbb2367069378e4ec415765a9606740da333b32631d3430c42fd7b5691b434329ef1ff2f6a0c19433d5149837bf4880d9
-  data.tar.gz: 256d27b3b35c9e6e569fe60098885fa878fa6e7df06ffed8330c58d5b611f198a796df6928a62c6f8c2df01e4628312e5a6408efab669511dc4a402a8ab7b6e8
+  metadata.gz: f803ca1e9d3dae3b791cebe930d49c221b2cd3f68df6cc5734bc3e40103af0d101db4447851596c2f6834b855f08a110c24455b06c517aa62e51b95a23cbdfd2
+  data.tar.gz: 844f53d23060359a77314f196fdeab023a7ded7c67fdea9f1a75b80bb28db3efb2421977001c13b3ec37f84479f6b9bf816e53a4a8da92c89bc58ee211b88ab8

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.3.0](https://github.com/bottrall/acp-sdk/compare/v0.2.0...v0.3.0) (2026-10-02)
+
+
+### Features
+
+* named protocol error codes ([#52](https://github.com/bottrall/acp-sdk/issues/52)) ([0a81700](https://github.com/bottrall/acp-sdk/commit/0a81700e3fa095279a77e2f161a7d6369c46792f))
+* spawn an agent process for ACP::ClientConnection ([#54](https://github.com/bottrall/acp-sdk/issues/54)) ([e01d2d2](https://github.com/bottrall/acp-sdk/commit/e01d2d280e9cfd08c203f6dccd1ce602979e21c8))
+
+## [0.2.0](https://github.com/bottrall/acp-sdk/compare/v0.1.0...v0.2.0) (2026-09-30)
+
+
+### Features
+
+* authenticate on ACP::AgentConnection ([#23](https://github.com/bottrall/acp-sdk/issues/23)) ([aac2bdd](https://github.com/bottrall/acp-sdk/commit/aac2bddbada2108bad3397d8f2c7bcdd617e8e0f))
+* filesystem methods on ACP::AgentConnection::Client ([#20](https://github.com/bottrall/acp-sdk/issues/20)) ([a15d942](https://github.com/bottrall/acp-sdk/commit/a15d942d1fe48cd7042732f64ea6d94cdd191549)), closes [#10](https://github.com/bottrall/acp-sdk/issues/10)
+* optional session methods on ACP::AgentConnection ([#24](https://github.com/bottrall/acp-sdk/issues/24)) ([952f906](https://github.com/bottrall/acp-sdk/commit/952f906e32bf455bac40effeb3d32fa6dea95904))
+* terminal methods on ACP::AgentConnection::Client ([#22](https://github.com/bottrall/acp-sdk/issues/22)) ([b4108b8](https://github.com/bottrall/acp-sdk/commit/b4108b8570a36d78a2c1231c04f7c1f697848318))
+
 ## 0.1.0 (2026-09-30)
 
 

data/README.md

@@ -1,20 +1,43 @@
 # acp-sdk
 
-A standalone Ruby implementation of the [Agent Client Protocol](https://agentclientprotocol.com) (ACP): the agent side (`ACP::AgentConnection`), for exposing an agent to ACP clients such as Zed and JetBrains, and the client side (`ACP::ClientConnection`), for driving ACP agents from Ruby.
+[![Gem Version](https://badge.fury.io/rb/acp-sdk.svg)](https://rubygems.org/gems/acp-sdk)
 
-Namespace `ACP`. MIT licensed.
+A Ruby SDK for the [Agent Client Protocol](https://agentclientprotocol.com) (ACP). It covers both sides of the protocol:
 
-## Status
+- **Agent side** (`ACP::AgentConnection`): expose your agent to ACP clients such as Zed and JetBrains.
+- **Client side** (`ACP::ClientConnection`): drive ACP agents from Ruby, for an editor integration or for tests.
 
-Intent only. Nothing is published yet; the `acp-sdk` gem name is claimed at the first release.
+Every ACP request, response and notification is a generated Ruby class under `ACP::Types`, and messages travel as JSON-RPC over stdio. The SDK speaks ACP protocol version 1.
 
-This repo exists so that [riffer-rig](https://github.com/bottrall/riffer-rig) can depend on it for its `riffer acp` host. Scope for the first release: JSON-RPC over stdio, `mcpServers` and `available_commands` in, permission requests and filesystem methods out.
+## Installation
+
+Requires Ruby 4.0 or later.
+
+Add the gem to your Gemfile:
+
+```sh
+bundle add acp-sdk
+```
+
+Or install it directly:
+
+```sh
+gem install acp-sdk
+```
+
+Then require it:
+
+```ruby
+require 'acp/sdk'
+```
 
 ## Serving an agent
 
-An agent is a plain Ruby object. `ACP::AgentConnection` answers `initialize` itself, turns each request into its generated `ACP::Types` object, calls the agent, and sends back what it returns. The factory block receives an `ACP::AgentConnection::Client` handle, which the agent keeps for sending session updates and asking permission. [`examples/echo_agent.rb`](examples/echo_agent.rb) is a complete agent; `ruby examples/echo_agent.rb` serves it on stdio.
+An agent is a plain Ruby object. `ACP::AgentConnection` answers `initialize` itself, turns each request into its generated `ACP::Types` object, calls the agent, and sends back what it returns. The factory block receives an `ACP::AgentConnection::Client` handle, which the agent keeps for sending session updates, asking permission, reading and writing files, and running commands in terminals.
 
 ```ruby
+require 'acp/sdk'
+
 connection = ACP::AgentConnection.new(
   transport: ACP::Transport::Stdio.new(input: $stdin, output: $stdout),
   capabilities: ACP::Types::AgentCapabilities.new(load_session: true),
@@ -25,57 +48,59 @@ connection.start.join
 
 The agent's contract:
 
-- It defines `new_session`, `prompt` and `cancel`. `load_session` and `list_sessions` are required only when `capabilities` advertises `load_session` or `session_capabilities.list`; `start` raises `ArgumentError` when one is advertised but missing, and a method that is not advertised is answered with `-32601`. `session_created`, if defined, runs right after the `session/new` reply is sent.
-- Each request method returns its response type or an `ACP::Transport::ResponseError`, which is sent as the error reply. Params that do not match the schema are answered with `-32602` before the agent sees them.
+- 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.
+- 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.
+
+[`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`.
 
 ## Driving an agent
 
-`ACP::ClientConnection` is the other side of the same transport, for editors and for tests that drive an agent. Each method takes the request's generated `ACP::Types` object and returns its response type or the agent's `ACP::Transport::ResponseError`. `connect` sends `initialize`, which Ruby reserves 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.
+
+`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.
 
 ```ruby
-stdin, stdout, = Open3.popen2('ruby', 'examples/echo_agent.rb')
-connection = ACP::ClientConnection.new(
-  transport: ACP::Transport::Stdio.new(input: stdout, output: stdin),
+require 'acp/sdk'
+
+response = ACP::AgentProcess.spawn(
+  'my-agent', '--flag',
+  env: { 'API_KEY' => '...' },
+  cwd: Dir.pwd,
+  stderr: :capture,
   permission: ->(request) { ask_the_user(request) },
   updates: ->(notification) { show(notification) }
-)
-connection.start
-connection.connect(ACP::Types::InitializeRequest.new(protocol_version: 1))
-session = connection.session_new(ACP::Types::NewSessionRequest.new(cwd: Dir.pwd, mcp_servers: []))
-prompt = [ACP::Types::ContentBlock::Text.new(text: 'hello')]
-response = connection.session_prompt(ACP::Types::PromptRequest.new(session_id: session.session_id, prompt:)) do |update|
-  print update.content.text if update.is_a?(ACP::Types::SessionUpdate::AgentMessageChunk)
+) do |connection|
+  connection.connect(ACP::Types::InitializeRequest.new(protocol_version: 1))
+  session = connection.session_new(ACP::Types::NewSessionRequest.new(cwd: Dir.pwd, mcp_servers: []))
+  prompt = [ACP::Types::ContentBlock::Text.new(text: 'hello')]
+  connection.session_prompt(ACP::Types::PromptRequest.new(session_id: session.session_id, prompt:)) do |update|
+    print update.content.text if update.is_a?(ACP::Types::SessionUpdate::AgentMessageChunk)
+  end
 end
 ```
 
-- `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.
-- `permission` answers `session/request_permission` with an `ACP::Types::RequestPermissionResponse` or an `ACP::Transport::ResponseError`. It runs on its own thread, so it may block while the user decides, and `session_cancel` can be sent meanwhile.
+Any transport over a pair of IOs works too, so the connection can still be wired by hand when the agent is not a child process:
 
-## Development
-
-Every project chore is a script in `bin/`. The Rakefile behind them is an implementation detail; you never need to call rake directly.
-
-| Script          | What it does                                                                                   |
-| --------------- | ---------------------------------------------------------------------------------------------- |
-| `bin/setup`     | Install dependencies on a fresh checkout (gems + rbs collection)                               |
-| `bin/test`      | Run the test suite. Pass files and/or Minitest flags: `bin/test test/foo_test.rb -n /pattern/` |
-| `bin/lint`      | Run RuboCop. Arguments are forwarded, e.g. `bin/lint -a`                                       |
-| `bin/typecheck` | Check `lib/acp/types`, the rbs collection lockfile and `sig/generated` are current, then type-check with Steep |
-| `bin/rbs`       | Regenerate `sig/generated` from the inline annotations in `lib/`                               |
-| `bin/types`     | Regenerate `lib/acp/types` from `schema/schema.json`, then `sig/generated`                     |
-| `bin/rbs-watch` | Regenerate `sig/generated` whenever `lib/` changes                                             |
-| `bin/ci`        | Run everything CI runs, serially. Use before pushing                                           |
-| `bin/build`     | Build the gem into `pkg/`; the publish workflow runs this before `gem push`                    |
+```ruby
+connection = ACP::ClientConnection.new(
+  transport: ACP::Transport::Stdio.new(input: some_io, output: other_io),
+  permission: ->(request) { ask_the_user(request) },
+  updates: ->(notification) { show(notification) }
+)
+```
 
-## Releasing
+- `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.
+- `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.
 
-PR titles are [conventional commits](https://www.conventionalcommits.org/) and are linted in CI: `feat:` bumps the minor version, `fix:` bumps the patch, and `feat!:` marks a breaking change (also a minor bump while we are on 0.x). `chore:`, `docs:`, `ci:`, `refactor:` and `test:` never release. Squash-merging makes the title the commit on `main`.
+## Contributing
 
-[release-please](https://github.com/googleapis/release-please) keeps a release PR open that bumps `lib/acp/version.rb` and writes `CHANGELOG.md`. Merging that PR tags `vX.Y.Z`, creates the GitHub Release and publishes the gem to RubyGems.org through Trusted Publishing; nothing is pushed by hand. The first release is 0.1.0.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/bottrall/acp-sdk). See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and workflow. Everyone interacting in the project is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
 
-## Maintainer
+## License
 
-- Jake Bottrall - https://github.com/bottrall
+Released under the [MIT License](LICENSE.txt).

data/lib/acp/agent_connection/client.rb

@@ -31,9 +31,88 @@ class ACP::AgentConnection::Client
   # closes.
   #
   # @rbs request: ACP::Types::RequestPermissionRequest
-  # @rbs return: ACP::Types::RequestPermissionResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::RequestPermissionResponse | ACP::RequestError
   def request_permission(request)
-    result = @peer.request('session/request_permission', request.to_h)
-    result.error || ACP::Types::RequestPermissionResponse.from_h(result.value)
+    call('session/request_permission', ACP::Types::RequestPermissionResponse, request)
+  end
+
+  # @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
+
+    call('fs/read_text_file', ACP::Types::ReadTextFileResponse, request)
+  end
+
+  # @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
+
+    call('fs/write_text_file', ACP::Types::WriteTextFileResponse, request)
+  end
+
+  # @rbs request: ACP::Types::CreateTerminalRequest
+  # @rbs return: ACP::Types::CreateTerminalResponse | ACP::RequestError
+  def create_terminal(request)
+    terminal_call('terminal/create', ACP::Types::CreateTerminalResponse, request)
+  end
+
+  # @rbs request: ACP::Types::TerminalOutputRequest
+  # @rbs return: ACP::Types::TerminalOutputResponse | ACP::RequestError
+  def terminal_output(request)
+    terminal_call('terminal/output', ACP::Types::TerminalOutputResponse, request)
+  end
+
+  # @rbs request: ACP::Types::WaitForTerminalExitRequest
+  # @rbs return: ACP::Types::WaitForTerminalExitResponse | ACP::RequestError
+  def wait_for_terminal_exit(request)
+    terminal_call('terminal/wait_for_exit', ACP::Types::WaitForTerminalExitResponse, request)
+  end
+
+  # @rbs request: ACP::Types::KillTerminalRequest
+  # @rbs return: ACP::Types::KillTerminalResponse | ACP::RequestError
+  def kill_terminal(request)
+    terminal_call('terminal/kill', ACP::Types::KillTerminalResponse, request)
+  end
+
+  # @rbs request: ACP::Types::ReleaseTerminalRequest
+  # @rbs return: ACP::Types::ReleaseTerminalResponse | ACP::RequestError
+  def release_terminal(request)
+    terminal_call('terminal/release', ACP::Types::ReleaseTerminalResponse, request)
+  end
+
+  private
+
+  # @rbs rpc_method: String
+  # @rbs type: ACP::AgentConnection::_Parser
+  # @rbs request: ACP::AgentConnection::_Response
+  # @rbs return: untyped
+  def call(rpc_method, type, request)
+    result = @peer.request(rpc_method, request.to_h)
+    return result if result.is_a?(ACP::RequestError)
+
+    type.from_h(result)
+  end
+
+  # @rbs rpc_method: String
+  # @rbs type: ACP::AgentConnection::_Parser
+  # @rbs request: ACP::AgentConnection::_Response
+  # @rbs return: untyped
+  def terminal_call(rpc_method, type, request)
+    return 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/authenticate.rb

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

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

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

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

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

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

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

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

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

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

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

data/lib/acp/agent_connection/optional_method.rb

@@ -1,28 +1,4 @@
 # frozen_string_literal: true
 
-class ACP::AgentConnection::OptionalMethod
-  # @rbs @capability: ^(ACP::Types::AgentCapabilities) -> boolish
-
-  # @dynamic rpc_method
-  attr_reader :rpc_method #: String
-
-  # @dynamic agent_method
-  attr_reader :agent_method #: Symbol
-
-  # @rbs rpc_method: String
-  # @rbs agent_method: Symbol
-  # @rbs &capability: (ACP::Types::AgentCapabilities) -> boolish
-  # @rbs return: void
-  def initialize(rpc_method:, agent_method:, &capability)
-    @rpc_method = rpc_method
-    @agent_method = agent_method
-    @capability = capability
-    freeze
-  end
-
-  # @rbs capabilities: ACP::Types::AgentCapabilities
-  # @rbs return: bool
-  def advertised?(capabilities)
-    @capability.call(capabilities) ? true : false
-  end
+module ACP::AgentConnection::OptionalMethod
 end

data/lib/acp/agent_connection.rb

@@ -2,19 +2,25 @@
 
 class ACP::AgentConnection
   # @rbs @transport: ACP::AgentConnection::_Transport
-  # @rbs @capabilities: ACP::Types::AgentCapabilities
-  # @rbs @agent_info: ACP::Types::Implementation?
-  # @rbs @auth_methods: Array[ACP::Types::AuthMethod::t]
+  # @rbs @initialize_response: ACP::Types::InitializeResponse
   # @rbs @factory: ^(ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent
 
   PROTOCOL_VERSION = 1 #: Integer
-  INVALID_PARAMS = ACP::Transport::ResponseError.new(code: -32_602, message: 'Invalid params') #: ACP::Transport::ResponseError
   OPTIONAL = [
-    ACP::AgentConnection::OptionalMethod.new(rpc_method: 'session/load', agent_method: :load_session, &:load_session),
-    ACP::AgentConnection::OptionalMethod.new(rpc_method: 'session/list', agent_method: :list_sessions) do |capabilities|
-      capabilities.session_capabilities&.list
-    end
-  ].freeze #: Array[ACP::AgentConnection::OptionalMethod]
+    ACP::AgentConnection::OptionalMethod::LoadSession,
+    ACP::AgentConnection::OptionalMethod::ListSessions,
+    ACP::AgentConnection::OptionalMethod::Authenticate,
+    ACP::AgentConnection::OptionalMethod::ResumeSession,
+    ACP::AgentConnection::OptionalMethod::CloseSession,
+    ACP::AgentConnection::OptionalMethod::DeleteSession
+  ].freeze #: Array[ACP::AgentConnection::_OptionalMethod]
+  # The schema has no initialize capability for modes or config options: an
+  # agent offers them per session, in its session responses, so they are
+  # routed whenever the agent defines them.
+  PER_SESSION = {
+    'session/set_mode' => :change_session_mode,
+    'session/set_config_option' => :change_session_config_option
+  }.freeze #: Hash[String, Symbol]
 
   # @rbs transport: ACP::AgentConnection::_Transport
   # @rbs capabilities: ACP::Types::AgentCapabilities
@@ -24,9 +30,12 @@ class ACP::AgentConnection
   # @rbs return: void
   def initialize(transport:, capabilities:, agent_info: nil, auth_methods: [], &factory)
     @transport = transport
-    @capabilities = capabilities
-    @agent_info = agent_info
-    @auth_methods = auth_methods
+    @initialize_response = ACP::Types::InitializeResponse.new(
+      protocol_version: PROTOCOL_VERSION,
+      agent_capabilities: capabilities,
+      auth_methods:,
+      agent_info:
+    )
     @factory = factory
   end
 
@@ -34,11 +43,11 @@ class ACP::AgentConnection
   def start
     client = ACP::AgentConnection::Client.new(peer: @transport)
     agent = @factory.call(client)
-    advertised, unadvertised = OPTIONAL.partition { |method| method.advertised?(@capabilities) }
+    advertised, unadvertised = OPTIONAL.partition { |method| method.advertised?(@initialize_response) }
     missing = advertised.map(&:agent_method).reject { |name| agent.respond_to?(name) }
-    raise ArgumentError, "capabilities advertise methods the agent lacks: #{missing.join(', ')}" unless missing.empty?
+    raise ArgumentError, "initialize advertises methods the agent lacks: #{missing.join(', ')}" unless missing.empty?
 
-    unrouted = unadvertised.map(&:rpc_method)
+    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))
   end
 
@@ -46,17 +55,25 @@ class ACP::AgentConnection
 
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs client: ACP::AgentConnection::Client
-  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::Result | ACP::Transport::Reply)]
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
   def requests(agent, client)
-    # Safe: start drops the load/list handlers the capabilities do not
-    # advertise and checks the agent defines the rest.
-    full = agent #: ACP::AgentConnection::_Agent & ACP::AgentConnection::_LoadSession & ACP::AgentConnection::_ListSessions
+    # Safe: start drops the optional handlers initialize does not advertise
+    # or the agent does not define, and checks the agent defines the rest.
+    full = agent #: ACP::AgentConnection::_FullAgent
     {
       'initialize' => route(ACP::Types::InitializeRequest) { |request| connect(client, request) },
+      'authenticate' => route(ACP::Types::AuthenticateRequest) { |request| full.authenticate(request) },
       'session/new' => route(ACP::Types::NewSessionRequest) { |request| new_session(agent, request) },
-      'session/prompt' => route(ACP::Types::PromptRequest) { |request| respond(agent.prompt(request)) },
-      'session/load' => route(ACP::Types::LoadSessionRequest) { |request| respond(full.load_session(request)) },
-      'session/list' => route(ACP::Types::ListSessionsRequest) { |request| respond(full.list_sessions(request)) }
+      'session/prompt' => route(ACP::Types::PromptRequest) { |request| agent.prompt(request) },
+      'session/load' => route(ACP::Types::LoadSessionRequest) { |request| full.load_session(request) },
+      'session/list' => route(ACP::Types::ListSessionsRequest) { |request| full.list_sessions(request) },
+      '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) },
+      '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)
+      end
     }
   end
 
@@ -69,40 +86,24 @@ class ACP::AgentConnection
   # Generated from_h raises on a missing key or a value of the wrong shape.
   #
   # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs &handle: (untyped) -> (ACP::Transport::Result | ACP::Transport::Reply)
-  # @rbs return: ^(untyped) -> (ACP::Transport::Result | ACP::Transport::Reply)
+  # @rbs &handle: (untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs return: ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
   def route(type, &)
     lambda do |params|
       request = type.from_h(params)
     rescue KeyError, TypeError, NoMethodError
-      ACP::Transport::Result.error(INVALID_PARAMS)
+      ACP::RequestError.invalid_params
     else
       yield(request)
     end
   end
 
-  # @rbs response: ACP::AgentConnection::_Response | ACP::Transport::ResponseError
-  # @rbs return: ACP::Transport::Result
-  def respond(response)
-    case response
-    when ACP::Transport::ResponseError then ACP::Transport::Result.error(response)
-    else ACP::Transport::Result.ok(response.to_h)
-    end
-  end
-
   # @rbs client: ACP::AgentConnection::Client
   # @rbs request: ACP::Types::InitializeRequest
-  # @rbs return: ACP::Transport::Result
+  # @rbs return: ACP::Types::InitializeResponse
   def connect(client, request)
     client.capabilities = request.client_capabilities || ACP::Types::ClientCapabilities.new
-    respond(
-      ACP::Types::InitializeResponse.new(
-        protocol_version: PROTOCOL_VERSION,
-        agent_capabilities: @capabilities,
-        auth_methods: @auth_methods,
-        agent_info: @agent_info
-      )
-    )
+    @initialize_response
   end
 
   # session_created runs after the reply because the client must know the
@@ -110,13 +111,12 @@ class ACP::AgentConnection
   #
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs request: ACP::Types::NewSessionRequest
-  # @rbs return: ACP::Transport::Result | ACP::Transport::Reply
+  # @rbs return: (ACP::Types::NewSessionResponse | ACP::RequestError | ACP::Transport::Reply)
   def new_session(agent, request)
     response = agent.new_session(request)
-    result = respond(response)
-    return result unless response.is_a?(ACP::Types::NewSessionResponse) && agent.respond_to?(:session_created)
+    return response unless response.is_a?(ACP::Types::NewSessionResponse) && agent.respond_to?(:session_created)
 
     hook = agent #: ACP::AgentConnection::_Agent & ACP::AgentConnection::_SessionCreated
-    ACP::Transport::Reply.new(result, after: -> { hook.session_created(response) })
+    ACP::Transport::Reply.new(response, after: -> { hook.session_created(response) })
   end
 end