acp-sdk 0.2.0 → 0.3.0

data/lib/acp/transport/stdio.rb

@@ -16,11 +16,9 @@ class ACP::Transport::Stdio
   # @rbs @next_id: Integer
   # @rbs @closed: bool
 
-  INTERNAL_ERROR = -32_603 #: Integer
-  PARSE_ERROR = ACP::Transport::ResponseError.new(code: -32_700, message: 'Parse error') #: ACP::Transport::ResponseError
-  INVALID_REQUEST = ACP::Transport::ResponseError.new(code: -32_600, message: 'Invalid request') #: ACP::Transport::ResponseError
-  METHOD_NOT_FOUND = ACP::Transport::ResponseError.new(code: -32_601, message: 'Method not found') #: ACP::Transport::ResponseError
-  CONNECTION_CLOSED = ACP::Transport::ResponseError.new(code: INTERNAL_ERROR, message: 'Connection closed') #: ACP::Transport::ResponseError
+  CONNECTION_CLOSED = ACP::RequestError.new(
+    code: ACP::RequestError::INTERNAL_ERROR, message: 'Connection closed'
+  ) #: ACP::RequestError
 
   # @rbs input: _Reader
   # @rbs output: _Writer
@@ -52,14 +50,14 @@ class ACP::Transport::Stdio
 
   # @rbs method: String
   # @rbs params: untyped
-  # @rbs return: ACP::Transport::Result
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
   def request(method, params = nil)
     queue = Thread::Queue.new
     id = register(queue)
-    return ACP::Transport::Result.error(CONNECTION_CLOSED) unless id
+    return CONNECTION_CLOSED unless id
 
     write({ 'jsonrpc' => '2.0', 'id' => id, 'method' => method, 'params' => params }.compact)
-    queue.pop || ACP::Transport::Result.error(CONNECTION_CLOSED)
+    queue.pop || CONNECTION_CLOSED
   end
 
   # @rbs method: String
@@ -78,7 +76,7 @@ class ACP::Transport::Stdio
   def receive(line, requests, notifications)
     message = parse(line)
     case message
-    when ACP::Transport::ResponseError then reply(nil, ACP::Transport::Result.error(message))
+    when ACP::RequestError then reply(nil, message)
     else route(message, requests, notifications)
     end
   end
@@ -98,25 +96,24 @@ class ACP::Transport::Stdio
       handler = notifications[method]
       quietly { handler.call(message['params']) } if handler
     elsif message.key?('result')
-      settle(message['id'], ACP::Transport::Result.ok(message['result']))
+      settle(message['id'], message['result'])
     elsif error.is_a?(Hash) && error['code'].is_a?(Integer) && error['message'].is_a?(String)
       code, text, data = error.values_at('code', 'message', 'data')
-      response_error = ACP::Transport::ResponseError.new(code:, message: text, data:)
-      settle(message['id'], ACP::Transport::Result.error(response_error))
+      settle(message['id'], ACP::RequestError.new(code:, message: text, data:))
     else
-      reply(nil, ACP::Transport::Result.error(INVALID_REQUEST))
+      reply(nil, ACP::RequestError.invalid_request)
     end
   end
 
   # @rbs line: String
-  # @rbs return: Hash[String, untyped] | ACP::Transport::ResponseError
+  # @rbs return: Hash[String, untyped] | ACP::RequestError
   def parse(line)
-    return PARSE_ERROR unless line.valid_encoding?
+    return ACP::RequestError.parse_error unless line.valid_encoding?
 
     message = JSON.parse(line)
-    message.is_a?(Hash) ? message : INVALID_REQUEST
+    message.is_a?(Hash) ? message : ACP::RequestError.invalid_request
   rescue JSON::ParserError
-    PARSE_ERROR
+    ACP::RequestError.parse_error
   end
 
   # @rbs handler: _Handler?
@@ -125,7 +122,7 @@ class ACP::Transport::Stdio
   # @rbs return: void
   def serve(handler, id, params)
     Thread.new do
-      outcome = handler ? invoke(handler, params) : ACP::Transport::Result.error(METHOD_NOT_FOUND)
+      outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found
       case outcome
       when ACP::Transport::Reply
         reply(id, outcome.result)
@@ -152,19 +149,25 @@ class ACP::Transport::Stdio
   #
   # @rbs handler: _Handler
   # @rbs params: untyped
-  # @rbs return: ACP::Transport::Result | ACP::Transport::Reply
+  # @rbs return: (_ToH | ACP::RequestError | ACP::Transport::Reply)
   def invoke(handler, params)
     handler.call(params)
   rescue StandardError => e
-    ACP::Transport::Result.error(ACP::Transport::ResponseError.new(code: INTERNAL_ERROR, message: e.message))
+    ACP::RequestError.new(code: ACP::RequestError::INTERNAL_ERROR, message: e.message)
   end
 
+  # The success arm is whatever the handler returned, which the transport only
+  # knows serializes with to_h; RequestError picks the error arm of the reply.
+  #
   # @rbs id: untyped
-  # @rbs result: ACP::Transport::Result
+  # @rbs outcome: (_ToH | ACP::RequestError)
   # @rbs return: void
-  def reply(id, result)
-    error = result.error
-    write({ 'jsonrpc' => '2.0', 'id' => id }.merge(error ? { 'error' => error.to_h } : { 'result' => result.value }))
+  def reply(id, outcome)
+    payload = case outcome
+              when ACP::RequestError then { 'error' => outcome.to_h }
+              else { 'result' => outcome.to_h }
+              end
+    write({ 'jsonrpc' => '2.0', 'id' => id }.merge(payload))
   end
 
   # @rbs queue: Thread::Queue
@@ -180,7 +183,7 @@ class ACP::Transport::Stdio
   end
 
   # @rbs id: untyped
-  # @rbs result: ACP::Transport::Result
+  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
   # @rbs return: void
   def settle(id, result)
     @lock.synchronize { @pending.delete(id) }&.push(result)

data/lib/acp/version.rb

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

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

@@ -24,36 +24,36 @@ class ACP::AgentConnection::Client
   # closes.
   #
   # @rbs request: ACP::Types::RequestPermissionRequest
-  # @rbs return: ACP::Types::RequestPermissionResponse | ACP::Transport::ResponseError
-  def request_permission: (ACP::Types::RequestPermissionRequest request) -> (ACP::Types::RequestPermissionResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::RequestPermissionResponse | ACP::RequestError
+  def request_permission: (ACP::Types::RequestPermissionRequest request) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::ReadTextFileRequest
-  # @rbs return: ACP::Types::ReadTextFileResponse | ACP::Transport::ResponseError
-  def read_text_file: (ACP::Types::ReadTextFileRequest request) -> (ACP::Types::ReadTextFileResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::ReadTextFileResponse | ACP::RequestError
+  def read_text_file: (ACP::Types::ReadTextFileRequest request) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::WriteTextFileRequest
-  # @rbs return: ACP::Types::WriteTextFileResponse | ACP::Transport::ResponseError
-  def write_text_file: (ACP::Types::WriteTextFileRequest request) -> (ACP::Types::WriteTextFileResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::WriteTextFileResponse | ACP::RequestError
+  def write_text_file: (ACP::Types::WriteTextFileRequest request) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::CreateTerminalRequest
-  # @rbs return: ACP::Types::CreateTerminalResponse | ACP::Transport::ResponseError
-  def create_terminal: (ACP::Types::CreateTerminalRequest request) -> (ACP::Types::CreateTerminalResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::CreateTerminalResponse | ACP::RequestError
+  def create_terminal: (ACP::Types::CreateTerminalRequest request) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::TerminalOutputRequest
-  # @rbs return: ACP::Types::TerminalOutputResponse | ACP::Transport::ResponseError
-  def terminal_output: (ACP::Types::TerminalOutputRequest request) -> (ACP::Types::TerminalOutputResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::TerminalOutputResponse | ACP::RequestError
+  def terminal_output: (ACP::Types::TerminalOutputRequest request) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::WaitForTerminalExitRequest
-  # @rbs return: ACP::Types::WaitForTerminalExitResponse | ACP::Transport::ResponseError
-  def wait_for_terminal_exit: (ACP::Types::WaitForTerminalExitRequest request) -> (ACP::Types::WaitForTerminalExitResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::WaitForTerminalExitResponse | ACP::RequestError
+  def wait_for_terminal_exit: (ACP::Types::WaitForTerminalExitRequest request) -> (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::KillTerminalRequest
-  # @rbs return: ACP::Types::KillTerminalResponse | ACP::Transport::ResponseError
-  def kill_terminal: (ACP::Types::KillTerminalRequest request) -> (ACP::Types::KillTerminalResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::KillTerminalResponse | ACP::RequestError
+  def kill_terminal: (ACP::Types::KillTerminalRequest request) -> (ACP::Types::KillTerminalResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::ReleaseTerminalRequest
-  # @rbs return: ACP::Types::ReleaseTerminalResponse | ACP::Transport::ResponseError
-  def release_terminal: (ACP::Types::ReleaseTerminalRequest request) -> (ACP::Types::ReleaseTerminalResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::ReleaseTerminalResponse | ACP::RequestError
+  def release_terminal: (ACP::Types::ReleaseTerminalRequest request) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
 
   private
 
@@ -68,4 +68,11 @@ 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

@@ -9,8 +9,6 @@ class ACP::AgentConnection
 
   PROTOCOL_VERSION: Integer
 
-  INVALID_PARAMS: ACP::Transport::ResponseError
-
   OPTIONAL: Array[ACP::AgentConnection::_OptionalMethod]
 
   # The schema has no initialize capability for modes or config options: an
@@ -33,8 +31,8 @@ class ACP::AgentConnection
 
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs client: ACP::AgentConnection::Client
-  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::Result | ACP::Transport::Reply)]
-  def requests: (ACP::AgentConnection::_Agent agent, ACP::AgentConnection::Client client) -> Hash[String, ^(untyped) -> (ACP::Transport::Result | ACP::Transport::Reply)]
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
+  def requests: (ACP::AgentConnection::_Agent agent, ACP::AgentConnection::Client client) -> Hash[String, ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)]
 
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs return: Hash[String, ^(untyped) -> void]
@@ -43,24 +41,20 @@ 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)
-  def route: (ACP::AgentConnection::_Parser type) { (untyped) -> (ACP::Transport::Result | ACP::Transport::Reply) } -> ^(untyped) -> (ACP::Transport::Result | ACP::Transport::Reply)
-
-  # @rbs response: ACP::AgentConnection::_Response | ACP::Transport::ResponseError
-  # @rbs return: ACP::Transport::Result
-  def respond: (ACP::AgentConnection::_Response | ACP::Transport::ResponseError response) -> ACP::Transport::Result
+  # @rbs &handle: (untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs return: ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
+  def route: (ACP::AgentConnection::_Parser type) { (untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply) } -> ^(untyped) -> (ACP::AgentConnection::_Response | ACP::RequestError | ACP::Transport::Reply)
 
   # @rbs client: ACP::AgentConnection::Client
   # @rbs request: ACP::Types::InitializeRequest
-  # @rbs return: ACP::Transport::Result
-  def connect: (ACP::AgentConnection::Client client, ACP::Types::InitializeRequest request) -> ACP::Transport::Result
+  # @rbs return: ACP::Types::InitializeResponse
+  def connect: (ACP::AgentConnection::Client client, ACP::Types::InitializeRequest request) -> ACP::Types::InitializeResponse
 
   # session_created runs after the reply because the client must know the
   # session id before updates for it (e.g. available commands) arrive.
   #
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs request: ACP::Types::NewSessionRequest
-  # @rbs return: ACP::Transport::Result | ACP::Transport::Reply
-  def new_session: (ACP::AgentConnection::_Agent agent, ACP::Types::NewSessionRequest request) -> (ACP::Transport::Result | ACP::Transport::Reply)
+  # @rbs return: (ACP::Types::NewSessionResponse | ACP::RequestError | ACP::Transport::Reply)
+  def new_session: (ACP::AgentConnection::_Agent agent, ACP::Types::NewSessionRequest request) -> (ACP::Types::NewSessionResponse | ACP::RequestError | ACP::Transport::Reply)
 end

data/sig/generated/acp/agent_process.rbs

@@ -0,0 +1,72 @@
+# Generated from lib/acp/agent_process.rb with RBS::Inline
+
+# A child agent process and the ACP::ClientConnection wired to its stdio.
+# Spawn one with ACP::AgentProcess.spawn.
+class ACP::AgentProcess
+  @stderr: String?
+
+  @err_reader: Thread?
+
+  @err_r: IO?
+
+  @waiter: Process::Waiter
+
+  @stdout: IO
+
+  @stdin: IO
+
+  @pid: Integer
+
+  @reader: Thread
+
+  @connection: ACP::ClientConnection
+
+  # @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: (String command, *String args, permission: ACP::ClientConnection::_PermissionHandler, ?env: Hash[String, String]?, ?cwd: String?, ?stderr: :inherit | :capture, ?updates: ACP::ClientConnection::_UpdateHandler) ?{ (ACP::ClientConnection, ACP::AgentProcess) -> untyped } -> (untyped | ACP::AgentProcess)
+
+  # 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: () -> void
+
+  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: ACP::ClientConnection, reader: Thread, stdin: IO, stdout: IO, waiter: Process::Waiter, err_r: IO?) -> void
+
+  # @rbs sig: String
+  # @rbs return: void
+  def signal: (String sig) -> void
+end

data/sig/generated/acp/client_connection.rbs

@@ -26,26 +26,26 @@ class ACP::ClientConnection
   # sent by connect.
   #
   # @rbs request: ACP::Types::InitializeRequest
-  # @rbs return: ACP::Types::InitializeResponse | ACP::Transport::ResponseError
-  def connect: (ACP::Types::InitializeRequest request) -> (ACP::Types::InitializeResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::InitializeResponse | ACP::RequestError
+  def connect: (ACP::Types::InitializeRequest request) -> (ACP::Types::InitializeResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::NewSessionRequest
-  # @rbs return: ACP::Types::NewSessionResponse | ACP::Transport::ResponseError
-  def session_new: (ACP::Types::NewSessionRequest request) -> (ACP::Types::NewSessionResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::NewSessionResponse | ACP::RequestError
+  def session_new: (ACP::Types::NewSessionRequest request) -> (ACP::Types::NewSessionResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::PromptRequest
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: ACP::Types::PromptResponse | ACP::Transport::ResponseError
-  def session_prompt: (ACP::Types::PromptRequest request) { (ACP::Types::SessionUpdate::t) -> void } -> (ACP::Types::PromptResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::PromptResponse | ACP::RequestError
+  def session_prompt: (ACP::Types::PromptRequest request) { (ACP::Types::SessionUpdate::t) -> void } -> (ACP::Types::PromptResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::LoadSessionRequest
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: ACP::Types::LoadSessionResponse | ACP::Transport::ResponseError
-  def session_load: (ACP::Types::LoadSessionRequest request) { (ACP::Types::SessionUpdate::t) -> void } -> (ACP::Types::LoadSessionResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::LoadSessionResponse | ACP::RequestError
+  def session_load: (ACP::Types::LoadSessionRequest request) { (ACP::Types::SessionUpdate::t) -> void } -> (ACP::Types::LoadSessionResponse | ACP::RequestError)
 
   # @rbs request: ACP::Types::ListSessionsRequest
-  # @rbs return: ACP::Types::ListSessionsResponse | ACP::Transport::ResponseError
-  def session_list: (ACP::Types::ListSessionsRequest request) -> (ACP::Types::ListSessionsResponse | ACP::Transport::ResponseError)
+  # @rbs return: ACP::Types::ListSessionsResponse | ACP::RequestError
+  def session_list: (ACP::Types::ListSessionsRequest request) -> (ACP::Types::ListSessionsResponse | ACP::RequestError)
 
   # @rbs notification: ACP::Types::CancelNotification
   # @rbs return: void
@@ -54,9 +54,9 @@ 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: (ACP::AgentConnection::_Parser type, ACP::Transport::Result result) -> untyped
+  def parse: (ACP::AgentConnection::_Parser type, Hash[String, untyped] | ACP::RequestError result) -> untyped
 
   # The request waits on its own thread so the caller's thread can yield each
   # update as it arrives. The reader thread queues an update before it settles
@@ -66,8 +66,8 @@ class ACP::ClientConnection
   # @rbs method: String
   # @rbs params: Hash[String, untyped]
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: ACP::Transport::Result
-  def stream: (String session_id, String method, Hash[String, untyped] params) { (ACP::Types::SessionUpdate::t) -> void } -> ACP::Transport::Result
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  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.
@@ -77,6 +77,6 @@ class ACP::ClientConnection
   def dispatch: (untyped params) -> void
 
   # @rbs params: untyped
-  # @rbs return: ACP::Transport::Result
-  def request_permission: (untyped params) -> ACP::Transport::Result
+  # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
+  def request_permission: (untyped params) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
 end

data/sig/generated/acp/request_error.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/acp/request_error.rb with RBS::Inline
+
+# 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: Integer
+
+  INVALID_REQUEST: Integer
+
+  METHOD_NOT_FOUND: Integer
+
+  INVALID_PARAMS: Integer
+
+  INTERNAL_ERROR: Integer
+
+  REQUEST_CANCELLED: Integer
+
+  AUTH_REQUIRED: Integer
+
+  RESOURCE_NOT_FOUND: Integer
+
+  # @rbs code: Integer
+  # @rbs message: String
+  # @rbs data: untyped
+  # @rbs return: void
+  def initialize: (code: Integer, message: String, ?data: untyped) -> void
+
+  # @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: () -> Hash[String, untyped]
+
+  # @rbs return: ACP::RequestError
+  def self.parse_error: () -> ACP::RequestError
+
+  # @rbs return: ACP::RequestError
+  def self.invalid_request: () -> ACP::RequestError
+
+  # @rbs return: ACP::RequestError
+  def self.method_not_found: () -> ACP::RequestError
+
+  # @rbs return: ACP::RequestError
+  def self.invalid_params: () -> ACP::RequestError
+
+  # @rbs return: ACP::RequestError
+  def self.internal_error: () -> ACP::RequestError
+
+  # @rbs return: ACP::RequestError
+  def self.request_cancelled: () -> ACP::RequestError
+
+  # @rbs return: ACP::RequestError
+  def self.auth_required: () -> ACP::RequestError
+
+  # @rbs uri: String?
+  # @rbs return: ACP::RequestError
+  def self.resource_not_found: (?String? uri) -> ACP::RequestError
+end

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

@@ -1,16 +1,16 @@
 # Generated from lib/acp/transport/reply.rb with RBS::Inline
 
-# 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: (ACP::Transport::Result result, after: ^() -> void) -> void
+  def initialize: (ACP::Transport::Stdio::_ToH result, after: ^() -> void) -> void
 end

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

@@ -20,15 +20,7 @@ class ACP::Transport::Stdio
 
   @input: _Reader
 
-  INTERNAL_ERROR: Integer
-
-  PARSE_ERROR: ACP::Transport::ResponseError
-
-  INVALID_REQUEST: ACP::Transport::ResponseError
-
-  METHOD_NOT_FOUND: ACP::Transport::ResponseError
-
-  CONNECTION_CLOSED: ACP::Transport::ResponseError
+  CONNECTION_CLOSED: ACP::RequestError
 
   # @rbs input: _Reader
   # @rbs output: _Writer
@@ -45,8 +37,8 @@ class ACP::Transport::Stdio
 
   # @rbs method: String
   # @rbs params: untyped
-  # @rbs return: ACP::Transport::Result
-  def request: (String method, ?untyped params) -> ACP::Transport::Result
+  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  def request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
 
   # @rbs method: String
   # @rbs params: untyped
@@ -68,8 +60,8 @@ class ACP::Transport::Stdio
   def route: (Hash[String, untyped] message, Hash[String, _Handler] requests, Hash[String, _NotificationHandler] notifications) -> void
 
   # @rbs line: String
-  # @rbs return: Hash[String, untyped] | ACP::Transport::ResponseError
-  def parse: (String line) -> (Hash[String, untyped] | ACP::Transport::ResponseError)
+  # @rbs return: Hash[String, untyped] | ACP::RequestError
+  def parse: (String line) -> (Hash[String, untyped] | ACP::RequestError)
 
   # @rbs handler: _Handler?
   # @rbs id: untyped
@@ -90,22 +82,25 @@ class ACP::Transport::Stdio
   #
   # @rbs handler: _Handler
   # @rbs params: untyped
-  # @rbs return: ACP::Transport::Result | ACP::Transport::Reply
-  def invoke: (_Handler handler, untyped params) -> (ACP::Transport::Result | ACP::Transport::Reply)
+  # @rbs return: (_ToH | ACP::RequestError | ACP::Transport::Reply)
+  def invoke: (_Handler handler, untyped params) -> (_ToH | ACP::RequestError | ACP::Transport::Reply)
 
+  # The success arm is whatever the handler returned, which the transport only
+  # knows serializes with to_h; RequestError picks the error arm of the reply.
+  #
   # @rbs id: untyped
-  # @rbs result: ACP::Transport::Result
+  # @rbs outcome: (_ToH | ACP::RequestError)
   # @rbs return: void
-  def reply: (untyped id, ACP::Transport::Result result) -> void
+  def reply: (untyped id, _ToH | ACP::RequestError outcome) -> void
 
   # @rbs queue: Thread::Queue
   # @rbs return: Integer?
   def register: (Thread::Queue queue) -> Integer?
 
   # @rbs id: untyped
-  # @rbs result: ACP::Transport::Result
+  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
   # @rbs return: void
-  def settle: (untyped id, ACP::Transport::Result result) -> void
+  def settle: (untyped id, Hash[String, untyped] | ACP::RequestError result) -> void
 
   # @rbs return: void
   def close: () -> void

data/sig/manual/acp/agent_connection.rbs

@@ -1,7 +1,7 @@
 class ACP::AgentConnection
   interface _Agent
-    def new_session: (ACP::Types::NewSessionRequest) -> (ACP::Types::NewSessionResponse | ACP::Transport::ResponseError)
-    def prompt: (ACP::Types::PromptRequest) -> (ACP::Types::PromptResponse | ACP::Transport::ResponseError)
+    def new_session: (ACP::Types::NewSessionRequest) -> (ACP::Types::NewSessionResponse | ACP::RequestError)
+    def prompt: (ACP::Types::PromptRequest) -> (ACP::Types::PromptResponse | ACP::RequestError)
     # Runs on the transport's reader thread, so it must return quickly.
     def cancel: (ACP::Types::CancelNotification) -> void
     # AgentConnection probes for the optional methods below.
@@ -9,35 +9,35 @@ class ACP::AgentConnection
   end
 
   interface _LoadSession
-    def load_session: (ACP::Types::LoadSessionRequest) -> (ACP::Types::LoadSessionResponse | ACP::Transport::ResponseError)
+    def load_session: (ACP::Types::LoadSessionRequest) -> (ACP::Types::LoadSessionResponse | ACP::RequestError)
   end
 
   interface _ListSessions
-    def list_sessions: (ACP::Types::ListSessionsRequest) -> (ACP::Types::ListSessionsResponse | ACP::Transport::ResponseError)
+    def list_sessions: (ACP::Types::ListSessionsRequest) -> (ACP::Types::ListSessionsResponse | ACP::RequestError)
   end
 
   interface _Authenticate
-    def authenticate: (ACP::Types::AuthenticateRequest) -> (ACP::Types::AuthenticateResponse | ACP::Transport::ResponseError)
+    def authenticate: (ACP::Types::AuthenticateRequest) -> (ACP::Types::AuthenticateResponse | ACP::RequestError)
   end
 
   interface _ResumeSession
-    def resume_session: (ACP::Types::ResumeSessionRequest) -> (ACP::Types::ResumeSessionResponse | ACP::Transport::ResponseError)
+    def resume_session: (ACP::Types::ResumeSessionRequest) -> (ACP::Types::ResumeSessionResponse | ACP::RequestError)
   end
 
   interface _CloseSession
-    def close_session: (ACP::Types::CloseSessionRequest) -> (ACP::Types::CloseSessionResponse | ACP::Transport::ResponseError)
+    def close_session: (ACP::Types::CloseSessionRequest) -> (ACP::Types::CloseSessionResponse | ACP::RequestError)
   end
 
   interface _DeleteSession
-    def delete_session: (ACP::Types::DeleteSessionRequest) -> (ACP::Types::DeleteSessionResponse | ACP::Transport::ResponseError)
+    def delete_session: (ACP::Types::DeleteSessionRequest) -> (ACP::Types::DeleteSessionResponse | ACP::RequestError)
   end
 
   interface _ChangeSessionMode
-    def change_session_mode: (ACP::Types::SetSessionModeRequest) -> (ACP::Types::SetSessionModeResponse | ACP::Transport::ResponseError)
+    def change_session_mode: (ACP::Types::SetSessionModeRequest) -> (ACP::Types::SetSessionModeResponse | ACP::RequestError)
   end
 
   interface _ChangeSessionConfigOption
-    def change_session_config_option: (ACP::Types::SetSessionConfigOptionRequest) -> (ACP::Types::SetSessionConfigOptionResponse | ACP::Transport::ResponseError)
+    def change_session_config_option: (ACP::Types::SetSessionConfigOptionRequest) -> (ACP::Types::SetSessionConfigOptionResponse | ACP::RequestError)
   end
 
   interface _FullAgent
@@ -66,19 +66,19 @@ class ACP::AgentConnection
   interface _Client
     def update: (String session_id, ACP::Types::SessionUpdate::t update) -> void
     def available_commands: (String session_id, Array[ACP::Types::AvailableCommand] commands) -> void
-    def request_permission: (ACP::Types::RequestPermissionRequest) -> (ACP::Types::RequestPermissionResponse | ACP::Transport::ResponseError)
-    def read_text_file: (ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::Transport::ResponseError)
-    def write_text_file: (ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::Transport::ResponseError)
-    def create_terminal: (ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::Transport::ResponseError)
-    def terminal_output: (ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::Transport::ResponseError)
-    def wait_for_terminal_exit: (ACP::Types::WaitForTerminalExitRequest) -> (ACP::Types::WaitForTerminalExitResponse | ACP::Transport::ResponseError)
-    def kill_terminal: (ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::Transport::ResponseError)
-    def release_terminal: (ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::Transport::ResponseError)
+    def request_permission: (ACP::Types::RequestPermissionRequest) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
+    def read_text_file: (ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
+    def write_text_file: (ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError)
+    def create_terminal: (ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError)
+    def terminal_output: (ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError)
+    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 capabilities: () -> ACP::Types::ClientCapabilities?
   end
 
   interface _Peer
-    def request: (String method, ?untyped params) -> ACP::Transport::Result
+    def request: (String method, ?untyped params) -> (Hash[String, untyped] | ACP::RequestError)
     def notify: (String method, ?untyped params) -> void
   end
 

data/sig/manual/acp/agent_process.rbs

@@ -0,0 +1,7 @@
+class ACP::AgentProcess
+  # The stdlib RBS for Open3#popen2 models neither the leading env hash nor
+  # the err: option, so spawn calls it through this narrower type.
+  interface _Spawner
+    def call: (*untyped, **untyped) -> [IO, IO, Process::Waiter]
+  end
+end

data/sig/manual/acp/client_connection.rbs

@@ -1,7 +1,7 @@
 class ACP::ClientConnection
   interface _PermissionHandler
     # Runs on its own thread, so it may block while the user decides.
-    def call: (ACP::Types::RequestPermissionRequest) -> (ACP::Types::RequestPermissionResponse | ACP::Transport::ResponseError)
+    def call: (ACP::Types::RequestPermissionRequest) -> (ACP::Types::RequestPermissionResponse | ACP::RequestError)
   end
 
   # Receives the session/update notifications that arrive outside a