acp-sdk 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fcba010891683b66eaf2fd2ae8bf9ae27e2aeb13b76666cc8c4478dfb7c4e9a
-  data.tar.gz: 5045a772ca2f080a7566ad3556a16087b3d15f4cbd39c3ed0ee5ae4dfe0ab521
+  metadata.gz: f0121ff621c45deb5578a15051611ea98d8d174193528c3df214fe4e036561ff
+  data.tar.gz: e26701095772e5bbf41a18a8e2bc9f4ac9609657aae1dee7c82891de6cf5b48c
 SHA512:
-  metadata.gz: c1a7eb1a2fc03be127272d8e3a97564c014691d1b582bd317f1da7b7022f250d603a09a811ef1271a9133e2bcf2fa5a6c7cde1f7d7ffe8c08a1f37fa28080d71
-  data.tar.gz: 4d006a52359dfdde15978220b83b9d7b10251b44c73a66c43be7a4259c0646a559b39ee05b09b1010e6b0108a95945751ad2cf0ffea4c6f9f1be041a0d4efbfa
+  metadata.gz: 66f390b3cf58c661064fe12ca5c7bbf04f560a81187f8cd37cce6d820870eb9f83717b655d04305a9a926e3cc08af618c1956acb7c2425899d2d3238e05d2651
+  data.tar.gz: 13853bc47c5c15a249296d9418fb951f52d512fea28f92fe9bf601c1a3e43d98840cbbbbfc181ff53150572db0393388553bf27f3c1746ca135f0467905d4270

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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)
+
+
+### 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)
 
 

data/README.md

@@ -48,41 +48,54 @@ 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.
-- 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, 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::Transport::ResponseError`. 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::Transport::ResponseError`. Unless `client.capabilities` advertises `terminal`, they return `-32601` without sending anything to the client. The agent must release every terminal it creates.
+- `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. 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`, 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.
+
+`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
 require 'acp/sdk'
-require 'open3'
 
-stdin, stdout, = Open3.popen2('my-agent')
+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) }
+) 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
+```
+
+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:
+
+```ruby
 connection = ACP::ClientConnection.new(
-  transport: ACP::Transport::Stdio.new(input: stdout, output: stdin),
+  transport: ACP::Transport::Stdio.new(input: some_io, output: other_io),
   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)
-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.
+- `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.
 
 ## Contributing
 

data/lib/acp/agent_connection/client.rb

@@ -31,53 +31,53 @@ 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)
     call('session/request_permission', ACP::Types::RequestPermissionResponse, request)
   end
 
   # @rbs request: ACP::Types::ReadTextFileRequest
-  # @rbs return: ACP::Types::ReadTextFileResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::ReadTextFileResponse | ACP::RequestError
   def read_text_file(request)
-    return ACP::Transport::Stdio::METHOD_NOT_FOUND unless capabilities&.fs&.read_text_file
+    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::Transport::ResponseError
+  # @rbs return: ACP::Types::WriteTextFileResponse | ACP::RequestError
   def write_text_file(request)
-    return ACP::Transport::Stdio::METHOD_NOT_FOUND unless capabilities&.fs&.write_text_file
+    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::Transport::ResponseError
+  # @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::Transport::ResponseError
+  # @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::Transport::ResponseError
+  # @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::Transport::ResponseError
+  # @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::Transport::ResponseError
+  # @rbs return: ACP::Types::ReleaseTerminalResponse | ACP::RequestError
   def release_terminal(request)
     terminal_call('terminal/release', ACP::Types::ReleaseTerminalResponse, request)
   end
@@ -90,7 +90,11 @@ class ACP::AgentConnection::Client
   # @rbs return: untyped
   def call(rpc_method, type, request)
     result = @peer.request(rpc_method, request.to_h)
-    result.error || type.from_h(result.value)
+    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
@@ -98,8 +102,19 @@ class ACP::AgentConnection::Client
   # @rbs request: ACP::AgentConnection::_Response
   # @rbs return: untyped
   def terminal_call(rpc_method, type, request)
-    return ACP::Transport::Stdio::METHOD_NOT_FOUND unless capabilities&.terminal
+    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/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

@@ -6,14 +6,14 @@ class ACP::AgentConnection
   # @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::LoadSession,
     ACP::AgentConnection::OptionalMethod::ListSessions,
     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
@@ -56,26 +56,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 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| respond(full.authenticate(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/resume' => route(ACP::Types::ResumeSessionRequest) { |request| respond(full.resume_session(request)) },
-      'session/close' => route(ACP::Types::CloseSessionRequest) { |request| respond(full.close_session(request)) },
-      'session/delete' => route(ACP::Types::DeleteSessionRequest) { |request| respond(full.delete_session(request)) },
-      'session/set_mode' => route(ACP::Types::SetSessionModeRequest) do |request|
-        respond(full.change_session_mode(request))
-      end,
+      '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) },
+      '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|
-        respond(full.change_session_config_option(request))
+        full.change_session_config_option(request)
       end
     }
   end
@@ -89,33 +88,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(@initialize_response)
+    @initialize_response
   end
 
   # session_created runs after the reply because the client must know the
@@ -123,13 +113,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

data/lib/acp/agent_process.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+# A child agent process and the ACP::ClientConnection wired to its stdio.
+# Spawn one with ACP::AgentProcess.spawn.
+class ACP::AgentProcess
+  # @rbs @connection: ACP::ClientConnection
+  # @rbs @reader: Thread
+  # @rbs @pid: Integer
+  # @rbs @stdin: IO
+  # @rbs @stdout: IO
+  # @rbs @waiter: Process::Waiter
+  # @rbs @err_r: IO?
+  # @rbs @err_reader: Thread?
+  # @rbs @stderr: String?
+
+  # @dynamic pid
+  attr_reader :pid #: Integer
+
+  # @dynamic connection
+  attr_reader :connection #: ACP::ClientConnection
+
+  # Child stderr captured when spawn was given stderr: :capture, else nil.
+  #
+  # @dynamic stderr
+  attr_reader :stderr #: String?
+
+  # Starts a command with args, env and cwd, wires its stdio to a new
+  # ACP::ClientConnection and starts it. With a block, yields the connection
+  # and this process, then terminates the child when the block exits; without
+  # one, returns the process and terminate is the caller's job.
+  #
+  # @rbs command: String
+  # @rbs *args: String
+  # @rbs env: Hash[String, String]?
+  # @rbs cwd: String?
+  # @rbs stderr: (:inherit | :capture)
+  # @rbs permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs &block: ? (ACP::ClientConnection, ACP::AgentProcess) -> untyped
+  # @rbs return: (untyped | ACP::AgentProcess)
+  def self.spawn(
+    command,
+    *args,
+    permission:,
+    env: nil,
+    cwd: nil,
+    stderr: :inherit,
+    updates: ACP::ClientConnection::IGNORE,
+    &block
+  )
+    err_r, err_w = stderr == :capture ? IO.pipe : nil
+    opts = {} #: Hash[Symbol, untyped]
+    opts[:chdir] = cwd if cwd
+    opts[:err] = err_w if err_w
+    spawner = Open3.method(:popen2) #: _Spawner
+    stdin, stdout, waiter = spawner.call(*(env ? [env, command, *args] : [command, *args]), **opts)
+    err_w&.close
+    connection = ACP::ClientConnection.new(
+      transport: ACP::Transport::Stdio.new(input: stdout, output: stdin),
+      permission:,
+      updates:
+    )
+    process = new(connection:, reader: connection.start, stdin:, stdout:, waiter:, err_r:)
+    return process unless block
+
+    begin
+      yield connection, process
+    ensure
+      process.terminate
+    end
+  end
+
+  # Closes stdin, waits for the child to exit — sending TERM and then KILL if
+  # it will not — and joins the transport reader before closing the pipe it
+  # reads.
+  #
+  # @rbs return: void
+  def terminate
+    @stdin.close unless @stdin.closed?
+    @waiter.join(1) or signal('TERM')
+    @waiter.join(2) or signal('KILL')
+    @waiter.join(2)
+    @reader.join(1)
+    @stdout.close unless @stdout.closed?
+    @err_reader&.join(1)
+    @err_r&.close unless @err_r&.closed?
+  end
+
+  private
+
+  # @rbs connection: ACP::ClientConnection
+  # @rbs reader: Thread
+  # @rbs stdin: IO
+  # @rbs stdout: IO
+  # @rbs waiter: Process::Waiter
+  # @rbs err_r: IO?
+  # @rbs return: void
+  def initialize(connection:, reader:, stdin:, stdout:, waiter:, err_r:)
+    @connection = connection
+    @reader = reader
+    @pid = waiter.pid
+    @stdin = stdin
+    @stdout = stdout
+    @waiter = waiter
+    @err_r = err_r
+    @stderr = err_r ? +'' : nil
+    @err_reader = Thread.new { err_r.each_line { |line| @stderr&.concat(line) } } if err_r
+  end
+
+  # @rbs sig: String
+  # @rbs return: void
+  def signal(sig)
+    Process.kill(sig, @pid)
+  rescue Errno::ESRCH
+    nil
+  end
+end

data/lib/acp/client_connection.rb

@@ -33,33 +33,33 @@ class ACP::ClientConnection
   # sent by connect.
   #
   # @rbs request: ACP::Types::InitializeRequest
-  # @rbs return: ACP::Types::InitializeResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::InitializeResponse | ACP::RequestError
   def connect(request)
     parse(ACP::Types::InitializeResponse, @transport.request('initialize', request.to_h))
   end
 
   # @rbs request: ACP::Types::NewSessionRequest
-  # @rbs return: ACP::Types::NewSessionResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::NewSessionResponse | ACP::RequestError
   def session_new(request)
     parse(ACP::Types::NewSessionResponse, @transport.request('session/new', request.to_h))
   end
 
   # @rbs request: ACP::Types::PromptRequest
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: ACP::Types::PromptResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::PromptResponse | ACP::RequestError
   def session_prompt(request, &)
     parse(ACP::Types::PromptResponse, stream(request.session_id, 'session/prompt', request.to_h, &))
   end
 
   # @rbs request: ACP::Types::LoadSessionRequest
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: ACP::Types::LoadSessionResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::LoadSessionResponse | ACP::RequestError
   def session_load(request, &)
     parse(ACP::Types::LoadSessionResponse, stream(request.session_id, 'session/load', request.to_h, &))
   end
 
   # @rbs request: ACP::Types::ListSessionsRequest
-  # @rbs return: ACP::Types::ListSessionsResponse | ACP::Transport::ResponseError
+  # @rbs return: ACP::Types::ListSessionsResponse | ACP::RequestError
   def session_list(request)
     parse(ACP::Types::ListSessionsResponse, @transport.request('session/list', request.to_h))
   end
@@ -73,10 +73,14 @@ class ACP::ClientConnection
   private
 
   # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs result: ACP::Transport::Result
+  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
   # @rbs return: untyped
   def parse(type, result)
-    result.error || type.from_h(result.value)
+    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
@@ -87,7 +91,7 @@ class ACP::ClientConnection
   # @rbs method: String
   # @rbs params: Hash[String, untyped]
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: ACP::Transport::Result
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
   def stream(session_id, method, params)
     queue = Thread::Queue.new
     @lock.synchronize { @streams[session_id] = queue }
@@ -114,16 +118,12 @@ class ACP::ClientConnection
   end
 
   # @rbs params: untyped
-  # @rbs return: ACP::Transport::Result
+  # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
   def request_permission(params)
     request = ACP::Types::RequestPermissionRequest.from_h(params)
   rescue KeyError, TypeError, NoMethodError
-    ACP::Transport::Result.error(ACP::AgentConnection::INVALID_PARAMS)
+    ACP::RequestError.invalid_params
   else
-    response = @permission.call(request)
-    case response
-    when ACP::Transport::ResponseError then ACP::Transport::Result.error(response)
-    else ACP::Transport::Result.ok(response.to_h)
-    end
+    @permission.call(request)
   end
 end

data/lib/acp/request_error.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# The schema's JSON-RPC Error object, named after the official SDKs'
+# RequestError: built by handlers and local refusals, and decoded from a
+# peer's error replies by the transport.
+class ACP::RequestError
+  PARSE_ERROR = -32_700 #: Integer
+  INVALID_REQUEST = -32_600 #: Integer
+  METHOD_NOT_FOUND = -32_601 #: Integer
+  INVALID_PARAMS = -32_602 #: Integer
+  INTERNAL_ERROR = -32_603 #: Integer
+  REQUEST_CANCELLED = -32_800 #: Integer
+  AUTH_REQUIRED = -32_000 #: Integer
+  RESOURCE_NOT_FOUND = -32_002 #: Integer
+
+  # @rbs code: Integer
+  # @rbs message: String
+  # @rbs data: untyped
+  # @rbs return: void
+  def initialize(code:, message:, data: nil)
+    @code = code
+    @message = message
+    @data = data
+    freeze
+  end
+
+  # @dynamic code
+  attr_reader :code #: Integer
+
+  # @dynamic message
+  attr_reader :message #: String
+
+  # @dynamic data
+  attr_reader :data #: untyped
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'code' => code, 'message' => message, 'data' => data }.compact
+  end
+
+  # @rbs return: ACP::RequestError
+  def self.parse_error
+    new(code: PARSE_ERROR, message: 'Parse error')
+  end
+
+  # @rbs return: ACP::RequestError
+  def self.invalid_request
+    new(code: INVALID_REQUEST, message: 'Invalid request')
+  end
+
+  # @rbs return: ACP::RequestError
+  def self.method_not_found
+    new(code: METHOD_NOT_FOUND, message: 'Method not found')
+  end
+
+  # @rbs return: ACP::RequestError
+  def self.invalid_params
+    new(code: INVALID_PARAMS, message: 'Invalid params')
+  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
+
+  # @rbs return: ACP::RequestError
+  def self.request_cancelled
+    new(code: REQUEST_CANCELLED, message: 'Request cancelled')
+  end
+
+  # @rbs return: ACP::RequestError
+  def self.auth_required
+    new(code: AUTH_REQUIRED, message: 'Authentication required')
+  end
+
+  # @rbs uri: String?
+  # @rbs return: ACP::RequestError
+  def self.resource_not_found(uri = nil)
+    new(code: RESOURCE_NOT_FOUND, message: 'Resource not found', data: uri && { uri: uri })
+  end
+end

data/lib/acp/transport/reply.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-# A request handler's result plus a callback the transport runs once that
-# result is on the wire, for messages the peer must only see after the reply.
+# A request handler's outcome plus a callback the transport runs once that
+# outcome is on the wire, for messages the peer must only see after the reply.
 class ACP::Transport::Reply
   # @dynamic result
-  attr_reader :result #: ACP::Transport::Result
+  attr_reader :result #: ACP::Transport::Stdio::_ToH
 
   # @dynamic after
   attr_reader :after #: ^() -> void
 
-  # @rbs result: ACP::Transport::Result
+  # @rbs result: ACP::Transport::Stdio::_ToH
   # @rbs after: ^() -> void
   # @rbs return: void
   def initialize(result, after:)