acp-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b7ee3b18dbb3a538b575c1b3309f93bd84eab3566e4491d39646dde8f0114ff6
+  data.tar.gz: ef1b3bed3a05dea92f076f4ed67e8378a3893d522db9ffe76ad445810b5fb20e
+SHA512:
+  metadata.gz: 69232d2be95232917e3f3c25c0eb890cbb2367069378e4ec415765a9606740da333b32631d3430c42fd7b5691b434329ef1ff2f6a0c19433d5149837bf4880d9
+  data.tar.gz: 256d27b3b35c9e6e569fe60098885fa878fa6e7df06ffed8330c58d5b611f198a796df6928a62c6f8c2df01e4628312e5a6408efab669511dc4a402a8ab7b6e8

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-09-30)
+
+
+### Features
+
+* ACP::AgentConnection with the required methods, session/load and session/list ([#14](https://github.com/bottrall/acp-sdk/issues/14)) ([565798c](https://github.com/bottrall/acp-sdk/commit/565798cffa6a0a3a09c38d28fa2cc25db881650e))
+* ACP::ClientConnection ([#17](https://github.com/bottrall/acp-sdk/issues/17)) ([65fc83a](https://github.com/bottrall/acp-sdk/commit/65fc83a8cda8896c03090fe4bb59a59907418791)), closes [#6](https://github.com/bottrall/acp-sdk/issues/6)
+* JSON-RPC over NDJSON stdio transport with mid-turn multiplexing ([#9](https://github.com/bottrall/acp-sdk/issues/9)) ([ef5f7db](https://github.com/bottrall/acp-sdk/commit/ef5f7db50f4272161f010f14dd99e49f2526d68b))
+* vendor the ACP schema.json and generate the types ([#8](https://github.com/bottrall/acp-sdk/issues/8)) ([69c6ece](https://github.com/bottrall/acp-sdk/commit/69c6ece77ff1b785c8f7f20681e3af71a1cbaffa)), closes [#3](https://github.com/bottrall/acp-sdk/issues/3)

data/LICENSE.txt

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jake Bottrall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# 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.
+
+Namespace `ACP`. MIT licensed.
+
+## Status
+
+Intent only. Nothing is published yet; the `acp-sdk` gem name is claimed at the first release.
+
+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.
+
+## 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.
+
+```ruby
+connection = ACP::AgentConnection.new(
+  transport: ACP::Transport::Stdio.new(input: $stdin, output: $stdout),
+  capabilities: ACP::Types::AgentCapabilities.new(load_session: true),
+  agent_info: ACP::Types::Implementation.new(name: 'my-agent', version: '1.0.0')
+) { |client| MyAgent.new(client:) }
+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.
+- `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`.
+
+## 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.
+
+```ruby
+stdin, stdout, = Open3.popen2('ruby', 'examples/echo_agent.rb')
+connection = ACP::ClientConnection.new(
+  transport: ACP::Transport::Stdio.new(input: stdout, output: stdin),
+  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.
+
+## 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`                    |
+
+## Releasing
+
+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`.
+
+[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.
+
+## Maintainer
+
+- Jake Bottrall - https://github.com/bottrall

data/lib/acp/agent_connection/client.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class ACP::AgentConnection::Client
+  # @rbs @peer: ACP::AgentConnection::_Peer
+
+  # @dynamic capabilities, capabilities=
+  attr_accessor :capabilities #: ACP::Types::ClientCapabilities?
+
+  # @rbs peer: ACP::AgentConnection::_Peer
+  # @rbs return: void
+  def initialize(peer:)
+    @peer = peer
+    @capabilities = nil
+  end
+
+  # @rbs session_id: String
+  # @rbs update: ACP::Types::SessionUpdate::t
+  # @rbs return: void
+  def update(session_id, update)
+    @peer.notify('session/update', ACP::Types::SessionNotification.new(session_id:, update:).to_h)
+  end
+
+  # @rbs session_id: String
+  # @rbs commands: Array[ACP::Types::AvailableCommand]
+  # @rbs return: void
+  def available_commands(session_id, commands)
+    update(session_id, ACP::Types::SessionUpdate::AvailableCommandsUpdate.new(available_commands: commands))
+  end
+
+  # Blocks the calling thread until the client answers or the connection
+  # closes.
+  #
+  # @rbs request: ACP::Types::RequestPermissionRequest
+  # @rbs return: ACP::Types::RequestPermissionResponse | ACP::Transport::ResponseError
+  def request_permission(request)
+    result = @peer.request('session/request_permission', request.to_h)
+    result.error || ACP::Types::RequestPermissionResponse.from_h(result.value)
+  end
+end

data/lib/acp/agent_connection/optional_method.rb

@@ -0,0 +1,28 @@
+# 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
+end

data/lib/acp/agent_connection.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+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 @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]
+
+  # @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 &factory: (ACP::AgentConnection::Client) -> ACP::AgentConnection::_Agent
+  # @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
+    @factory = factory
+  end
+
+  # @rbs return: Thread
+  def start
+    client = ACP::AgentConnection::Client.new(peer: @transport)
+    agent = @factory.call(client)
+    advertised, unadvertised = OPTIONAL.partition { |method| method.advertised?(@capabilities) }
+    missing = advertised.map(&:agent_method).reject { |name| agent.respond_to?(name) }
+    raise ArgumentError, "capabilities advertise methods the agent lacks: #{missing.join(', ')}" unless missing.empty?
+
+    unrouted = unadvertised.map(&:rpc_method)
+    @transport.start(requests: requests(agent, client).except(*unrouted), notifications: notifications(agent))
+  end
+
+  private
+
+  # @rbs agent: ACP::AgentConnection::_Agent
+  # @rbs client: ACP::AgentConnection::Client
+  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::Result | 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
+    {
+      'initialize' => route(ACP::Types::InitializeRequest) { |request| connect(client, 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)) }
+    }
+  end
+
+  # @rbs agent: ACP::AgentConnection::_Agent
+  # @rbs return: Hash[String, ^(untyped) -> void]
+  def notifications(agent)
+    { 'session/cancel' => ->(params) { agent.cancel(ACP::Types::CancelNotification.from_h(params)) } }
+  end
+
+  # 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(type, &)
+    lambda do |params|
+      request = type.from_h(params)
+    rescue KeyError, TypeError, NoMethodError
+      ACP::Transport::Result.error(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
+  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
+      )
+    )
+  end
+
+  # 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(agent, request)
+    response = agent.new_session(request)
+    result = respond(response)
+    return result 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) })
+  end
+end

data/lib/acp/client_connection.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+class ACP::ClientConnection
+  # @rbs @transport: ACP::AgentConnection::_Transport
+  # @rbs @permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs @updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs @lock: Thread::Mutex
+  # @rbs @streams: Hash[String, Thread::Queue]
+
+  IGNORE = ->(_notification) {} #: ^(ACP::Types::SessionNotification) -> void
+
+  # @rbs transport: ACP::AgentConnection::_Transport
+  # @rbs permission: ACP::ClientConnection::_PermissionHandler
+  # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs return: void
+  def initialize(transport:, permission:, updates: IGNORE)
+    @transport = transport
+    @permission = permission
+    @updates = updates
+    @lock = Mutex.new
+    @streams = {}
+  end
+
+  # @rbs return: Thread
+  def start
+    @transport.start(
+      requests: { 'session/request_permission' => method(:request_permission) },
+      notifications: { 'session/update' => method(:dispatch) }
+    )
+  end
+
+  # Ruby reserves initialize for the constructor, so the initialize request is
+  # sent by connect.
+  #
+  # @rbs request: ACP::Types::InitializeRequest
+  # @rbs return: ACP::Types::InitializeResponse | ACP::Transport::ResponseError
+  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
+  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
+  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
+  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
+  def session_list(request)
+    parse(ACP::Types::ListSessionsResponse, @transport.request('session/list', request.to_h))
+  end
+
+  # @rbs notification: ACP::Types::CancelNotification
+  # @rbs return: void
+  def session_cancel(notification)
+    @transport.notify('session/cancel', notification.to_h)
+  end
+
+  private
+
+  # @rbs type: ACP::AgentConnection::_Parser
+  # @rbs result: ACP::Transport::Result
+  # @rbs return: untyped
+  def parse(type, result)
+    result.error || type.from_h(result.value)
+  end
+
+  # 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
+  # a reply sent after it, so the queue closes only after the last one.
+  #
+  # @rbs session_id: String
+  # @rbs method: String
+  # @rbs params: Hash[String, untyped]
+  # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
+  # @rbs return: ACP::Transport::Result
+  def stream(session_id, method, params)
+    queue = Thread::Queue.new
+    @lock.synchronize { @streams[session_id] = queue }
+    requester = Thread.new do
+      @transport.request(method, params)
+    ensure
+      @lock.synchronize { @streams.delete(session_id)&.close }
+    end
+    while (update = queue.pop)
+      yield update
+    end
+    requester.value
+  end
+
+  # Pushes under the lock so a stream cannot close its queue between the
+  # lookup and the push.
+  #
+  # @rbs params: untyped
+  # @rbs return: void
+  def dispatch(params)
+    notification = ACP::Types::SessionNotification.from_h(params)
+    queue = @lock.synchronize { @streams[notification.session_id]&.push(notification.update) }
+    @updates.call(notification) unless queue
+  end
+
+  # @rbs params: untyped
+  # @rbs return: ACP::Transport::Result
+  def request_permission(params)
+    request = ACP::Types::RequestPermissionRequest.from_h(params)
+  rescue KeyError, TypeError, NoMethodError
+    ACP::Transport::Result.error(ACP::AgentConnection::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
+  end
+end

data/lib/acp/sdk.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require_relative 'version'
+
+# The gem is `acp-sdk` but its namespace is `ACP`, so lib/acp is the root
+# directory for ACP rather than lib for a top-level constant.
+root = __dir__ #: String
+loader = Zeitwerk::Loader.new
+loader.tag = 'acp-sdk'
+loader.push_dir(root, namespace: ACP)
+loader.ignore(__FILE__, "#{root}/version.rb")
+loader.setup

data/lib/acp/transport/reply.rb

@@ -0,0 +1,20 @@
+# 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.
+class ACP::Transport::Reply
+  # @dynamic result
+  attr_reader :result #: ACP::Transport::Result
+
+  # @dynamic after
+  attr_reader :after #: ^() -> void
+
+  # @rbs result: ACP::Transport::Result
+  # @rbs after: ^() -> void
+  # @rbs return: void
+  def initialize(result, after:)
+    @result = result
+    @after = after
+    freeze
+  end
+end

data/lib/acp/transport/response_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class ACP::Transport::ResponseError
+  # @dynamic code
+  attr_reader :code #: Integer
+
+  # @dynamic message
+  attr_reader :message #: String
+
+  # @dynamic data
+  attr_reader :data #: untyped
+
+  # @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
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'code' => code, 'message' => message, 'data' => data }.compact
+  end
+end

data/lib/acp/transport/result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class ACP::Transport::Result
+  # @dynamic value
+  attr_reader :value #: untyped
+
+  # @dynamic error
+  attr_reader :error #: ACP::Transport::ResponseError?
+
+  # @rbs value: untyped
+  # @rbs return: ACP::Transport::Result
+  def self.ok(value)
+    new(value:, error: nil)
+  end
+
+  # @rbs error: ACP::Transport::ResponseError
+  # @rbs return: ACP::Transport::Result
+  def self.error(error)
+    new(value: nil, error:)
+  end
+
+  # @rbs value: untyped
+  # @rbs error: ACP::Transport::ResponseError?
+  # @rbs return: void
+  def initialize(value:, error:)
+    @value = value
+    @error = error
+    freeze
+  end
+
+  # @rbs return: bool
+  def ok?
+    error.nil?
+  end
+end