acp_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ffa79a20b8968e789ed0de24e3fa89bb528d7518a29e5609bff2569f0d41f5a
+  data.tar.gz: 52be0fd47071c8caac178a7340603853c0d7073263f37cd983b0fa823416efc1
+SHA512:
+  metadata.gz: 82f446bb9e4c1338e249b7c0b6a3972d13aeb1395b34792285aa6d7a6f681a825d3e2c741c286b51438df7ea7b2b0149b4a6c85fd27a5ff26adb62b4095c29c6
+  data.tar.gz: '0012968ff5ec5aa7878509dacea620de3c1c7f040e8d37398e08f3e9f9fb6777b09cef298372341b089466c9858d677db3182bdf3d0a582490978c7097dd1f4d'

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release: full ACP (Agent Client Protocol) SDK for Ruby
+- Code-generated schema types from upstream `schema.json` (v0.10.8)
+- Bidirectional JSON-RPC 2.0 transport over stdio (NDJSON framing)
+- Agent and client connection classes with symmetric calling pattern
+- Process management: `run_agent`, `spawn_agent_process`, `spawn_client_process`
+- Helper functions for building content blocks, tool calls, session updates
+- Contrib helpers: `SessionAccumulator`, `ToolCallTracker`, `PermissionBroker`
+- Examples: echo agent, interactive client, duet (both sides in one process)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Copeland
+
+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,125 @@
+# AgentClientProtocol
+
+[![Gem Version](https://badge.fury.io/rb/acp_ruby.svg)](https://badge.fury.io/rb/acp_ruby)
+
+Ruby SDK for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) — a JSON-RPC 2.0 based open protocol standardizing communication between code editors and AI coding agents.
+
+## Installation
+
+```sh
+bundle add acp_ruby
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "acp_ruby"
+```
+
+## Usage
+
+### Building an Agent
+
+```ruby
+require "agent_client_protocol"
+
+class MyAgent
+  include AgentClientProtocol::AgentInterface
+  include AgentClientProtocol::Helpers
+
+  def on_connect(conn)
+    @conn = conn
+  end
+
+  def initialize_agent(protocol_version:, **)
+    AgentClientProtocol::Schema::InitializeResponse.new(
+      protocol_version: 1,
+      agent_info: { name: "my-agent", version: "1.0.0" },
+      capabilities: {}
+    )
+  end
+
+  def new_session(cwd:, **)
+    AgentClientProtocol::Schema::NewSessionResponse.new(session_id: SecureRandom.uuid)
+  end
+
+  def prompt(prompt:, session_id:, **)
+    @conn.session_update(
+      session_id: session_id,
+      update: update_agent_message_text("You said: #{prompt}")
+    )
+    AgentClientProtocol::Schema::PromptResponse.new(
+      stop_reason: "end_turn"
+    )
+  end
+end
+
+AgentClientProtocol.run_agent(MyAgent.new)
+```
+
+### Building a Client
+
+```ruby
+require "agent_client_protocol"
+
+class MyClient
+  include AgentClientProtocol::ClientInterface
+
+  def on_connect(conn)
+    @conn = conn
+  end
+
+  def session_update(session_id:, update:, **)
+    puts "Update: #{update}"
+  end
+
+  def request_permission(session_id:, tool_call:, options:, **)
+    AgentClientProtocol::Schema::RequestPermissionResponse.new(
+      allowed: true
+    )
+  end
+end
+
+client = MyClient.new
+AgentClientProtocol.spawn_agent_process(client, "claude-code", "--acp") do |conn, pid|
+  resp = conn.initialize_agent(protocol_version: 1, client_info: { name: "my-client", version: "1.0.0" })
+  session = conn.new_session(cwd: Dir.pwd)
+  result = conn.prompt(session_id: session.session_id, prompt: "Hello!")
+  puts "Done: #{result.stop_reason}"
+end
+```
+
+### Spawning Both Sides in One Process
+
+```ruby
+require "agent_client_protocol"
+
+# See examples/duet.rb for a full working example
+```
+
+## Error Handling
+
+```ruby
+begin
+  conn.prompt(session_id: sid, prompt: "hello")
+rescue AgentClientProtocol::RequestError => e
+  puts "Error #{e.code}: #{e.message}"
+  puts "Data: #{e.data}" if e.data
+end
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec ruby script/generate_schema.rb  # regenerate schema types
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/davidcopeland/agent_client_protocol).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/acp_ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "agent_client_protocol"

data/lib/agent_client_protocol/agent/connection.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "router"
+
+module AgentClientProtocol
+  module Agent
+    class Connection
+      attr_reader :conn
+
+      def initialize(handler, reader, writer)
+        @handler = handler
+        router = Agent.build_router(handler)
+        @conn = AgentClientProtocol::Connection.new(
+          reader: reader,
+          writer: writer,
+          handler: router.method(:call)
+        )
+        handler.on_connect(self)
+      end
+
+      # --- Client-calling methods (agent sends to client) ---
+
+      def session_update(session_id:, update:)
+        params = Schema::SessionNotification.new(
+          session_id: session_id,
+          update: update
+        )
+        @conn.send_notification("session/update", params.to_h)
+      end
+
+      def request_permission(session_id:, tool_call:, options:)
+        params = Schema::RequestPermissionRequest.new(
+          session_id: session_id,
+          tool_call: tool_call.is_a?(Schema::BaseModel) ? tool_call : Schema::ToolCallUpdate.from_hash(tool_call),
+          options: options
+        )
+        result = @conn.send_request("session/request_permission", params.to_h)
+        Schema::RequestPermissionResponse.from_hash(result)
+      end
+
+      def read_text_file(session_id:, path:, line: nil, limit: nil)
+        params = Schema::ReadTextFileRequest.new(
+          session_id: session_id,
+          path: path,
+          line: line,
+          limit: limit
+        )
+        result = @conn.send_request("fs/read_text_file", params.to_h)
+        Schema::ReadTextFileResponse.from_hash(result)
+      end
+
+      def write_text_file(session_id:, path:, content:)
+        params = Schema::WriteTextFileRequest.new(
+          session_id: session_id,
+          path: path,
+          content: content
+        )
+        result = @conn.send_request("fs/write_text_file", params.to_h)
+        Schema::WriteTextFileResponse.from_hash(result)
+      end
+
+      def create_terminal(session_id:, command:, args: nil, cwd: nil, env: nil)
+        params = Schema::CreateTerminalRequest.new(
+          session_id: session_id,
+          command: command,
+          args: args,
+          cwd: cwd,
+          env: env
+        )
+        result = @conn.send_request("terminal/create", params.to_h)
+        Schema::CreateTerminalResponse.from_hash(result)
+      end
+
+      def terminal_output(session_id:, terminal_id:)
+        params = Schema::TerminalOutputRequest.new(
+          session_id: session_id,
+          terminal_id: terminal_id
+        )
+        result = @conn.send_request("terminal/output", params.to_h)
+        Schema::TerminalOutputResponse.from_hash(result)
+      end
+
+      def release_terminal(session_id:, terminal_id:)
+        params = Schema::ReleaseTerminalRequest.new(
+          session_id: session_id,
+          terminal_id: terminal_id
+        )
+        result = @conn.send_request("terminal/release", params.to_h)
+        Schema::ReleaseTerminalResponse.from_hash(result)
+      end
+
+      def wait_for_terminal_exit(session_id:, terminal_id:)
+        params = Schema::WaitForTerminalExitRequest.new(
+          session_id: session_id,
+          terminal_id: terminal_id
+        )
+        result = @conn.send_request("terminal/wait_for_exit", params.to_h)
+        Schema::WaitForTerminalExitResponse.from_hash(result)
+      end
+
+      def kill_terminal(session_id:, terminal_id:)
+        params = Schema::KillTerminalCommandRequest.new(
+          session_id: session_id,
+          terminal_id: terminal_id
+        )
+        result = @conn.send_request("terminal/kill", params.to_h)
+        Schema::KillTerminalCommandResponse.from_hash(result)
+      end
+
+      # --- Lifecycle ---
+
+      def listen
+        @conn.listen
+      end
+
+      def close
+        @conn.close
+      end
+
+      def closed?
+        @conn.closed?
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/agent/router.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Agent
+    S = Schema
+
+    module_function
+
+    def build_router(handler)
+      router = AgentClientProtocol::Router.new
+
+      router.on_request("initialize", request_class: S::InitializeRequest) do |params|
+        handler.initialize_agent(
+          protocol_version: params.protocol_version,
+          client_capabilities: params.client_capabilities,
+          client_info: params.client_info
+        )
+      end
+
+      router.on_request("authenticate", request_class: S::AuthenticateRequest, optional: true) do |params|
+        handler.authenticate(method_id: params.method_id)
+      end
+
+      router.on_request("session/new", request_class: S::NewSessionRequest) do |params|
+        handler.new_session(cwd: params.cwd, mcp_servers: params.mcp_servers)
+      end
+
+      router.on_request("session/load", request_class: S::LoadSessionRequest, optional: true) do |params|
+        handler.load_session(
+          cwd: params.cwd,
+          session_id: params.session_id,
+          mcp_servers: params.mcp_servers
+        )
+      end
+
+      router.on_request("session/prompt", request_class: S::PromptRequest) do |params|
+        handler.prompt(prompt: params.prompt, session_id: params.session_id)
+      end
+
+      router.on_notification("session/cancel", request_class: S::CancelNotification) do |params|
+        handler.cancel(session_id: params.session_id)
+      end
+
+      router.on_request("session/set_mode", request_class: S::SetSessionModeRequest, optional: true) do |params|
+        handler.set_session_mode(mode_id: params.mode_id, session_id: params.session_id)
+      end
+
+      router.on_request("session/set_config_option", request_class: S::SetSessionConfigOptionRequest, optional: true) do |params|
+        handler.set_config_option(
+          config_id: params.config_id,
+          session_id: params.session_id,
+          value: params.value
+        )
+      end
+
+      router.on_ext_method { |method, params| handler.ext_method(method, params) }
+      router.on_ext_notification { |method, params| handler.ext_notification(method, params) }
+
+      router
+    end
+  end
+end

data/lib/agent_client_protocol/agent.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module AgentInterface
+    def on_connect(conn)
+      raise NotImplementedError, "#{self.class}#on_connect"
+    end
+
+    def initialize_agent(protocol_version:, client_capabilities: nil, client_info: nil, **)
+      raise NotImplementedError, "#{self.class}#initialize_agent"
+    end
+
+    def new_session(cwd:, mcp_servers: nil, **)
+      raise NotImplementedError, "#{self.class}#new_session"
+    end
+
+    def prompt(prompt:, session_id:, **)
+      raise NotImplementedError, "#{self.class}#prompt"
+    end
+
+    def cancel(session_id:, **)
+      nil
+    end
+
+    def authenticate(method_id:, **)
+      raise NotImplementedError, "#{self.class}#authenticate"
+    end
+
+    def load_session(cwd:, session_id:, mcp_servers: nil, **)
+      nil
+    end
+
+    def set_session_mode(mode_id:, session_id:, **)
+      nil
+    end
+
+    def set_config_option(config_id:, session_id:, value:, **)
+      nil
+    end
+
+    def ext_method(method, params)
+      raise RequestError.method_not_found(method)
+    end
+
+    def ext_notification(method, params)
+      nil
+    end
+  end
+end

data/lib/agent_client_protocol/client/connection.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "router"
+
+module AgentClientProtocol
+  module Client
+    class Connection
+      attr_reader :conn
+
+      def initialize(handler, reader, writer)
+        @handler = handler
+        router = Client.build_router(handler)
+        @conn = AgentClientProtocol::Connection.new(
+          reader: reader,
+          writer: writer,
+          handler: router.method(:call)
+        )
+        handler.on_connect(self)
+      end
+
+      # --- Agent-calling methods (client sends to agent) ---
+
+      def initialize_agent(protocol_version:, client_capabilities: nil, client_info: nil)
+        params = Schema::InitializeRequest.new(
+          protocol_version: protocol_version,
+          client_capabilities: client_capabilities,
+          client_info: client_info
+        )
+        result = @conn.send_request("initialize", params.to_h)
+        Schema::InitializeResponse.from_hash(result)
+      end
+
+      def new_session(cwd:, mcp_servers: [])
+        params = Schema::NewSessionRequest.new(cwd: cwd, mcp_servers: mcp_servers)
+        result = @conn.send_request("session/new", params.to_h)
+        Schema::NewSessionResponse.from_hash(result)
+      end
+
+      def load_session(cwd:, session_id:, mcp_servers: [])
+        params = Schema::LoadSessionRequest.new(
+          cwd: cwd,
+          session_id: session_id,
+          mcp_servers: mcp_servers
+        )
+        result = @conn.send_request("session/load", params.to_h)
+        Schema::LoadSessionResponse.from_hash(result)
+      end
+
+      def prompt(session_id:, prompt:)
+        prompt_blocks = case prompt
+                        when String
+                          [Schema::TextContent.new(text: prompt).to_h]
+                        when Array
+                          prompt.map { |b| b.is_a?(Schema::BaseModel) ? b.to_h : b }
+                        else
+                          [prompt.is_a?(Schema::BaseModel) ? prompt.to_h : prompt]
+                        end
+
+        params = Schema::PromptRequest.new(
+          session_id: session_id,
+          prompt: prompt_blocks
+        )
+        result = @conn.send_request("session/prompt", params.to_h)
+        Schema::PromptResponse.from_hash(result)
+      end
+
+      def cancel(session_id:)
+        params = Schema::CancelNotification.new(session_id: session_id)
+        @conn.send_notification("session/cancel", params.to_h)
+      end
+
+      def authenticate(method_id:)
+        params = Schema::AuthenticateRequest.new(method_id: method_id)
+        result = @conn.send_request("authenticate", params.to_h)
+        Schema::AuthenticateResponse.from_hash(result)
+      end
+
+      def set_session_mode(session_id:, mode_id:)
+        params = Schema::SetSessionModeRequest.new(
+          session_id: session_id,
+          mode_id: mode_id
+        )
+        result = @conn.send_request("session/set_mode", params.to_h)
+        Schema::SetSessionModeResponse.from_hash(result)
+      end
+
+      def set_config_option(session_id:, config_id:, value:)
+        params = Schema::SetSessionConfigOptionRequest.new(
+          session_id: session_id,
+          config_id: config_id,
+          value: value
+        )
+        result = @conn.send_request("session/set_config_option", params.to_h)
+        Schema::SetSessionConfigOptionResponse.from_hash(result)
+      end
+
+      # --- Lifecycle ---
+
+      def listen
+        @conn.listen
+      end
+
+      def close
+        @conn.close
+      end
+
+      def closed?
+        @conn.closed?
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/client/router.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Client
+    S = Schema
+
+    module_function
+
+    def build_router(handler)
+      router = AgentClientProtocol::Router.new
+
+      router.on_notification("session/update", request_class: S::SessionNotification) do |params|
+        handler.session_update(session_id: params.session_id, update: params.update)
+      end
+
+      router.on_request("session/request_permission", request_class: S::RequestPermissionRequest) do |params|
+        handler.request_permission(
+          session_id: params.session_id,
+          tool_call: params.tool_call,
+          options: params.options
+        )
+      end
+
+      router.on_request("fs/read_text_file", request_class: S::ReadTextFileRequest, optional: true) do |params|
+        handler.read_text_file(
+          session_id: params.session_id,
+          path: params.path,
+          line: params.line,
+          limit: params.limit
+        )
+      end
+
+      router.on_request("fs/write_text_file", request_class: S::WriteTextFileRequest, optional: true) do |params|
+        handler.write_text_file(
+          session_id: params.session_id,
+          path: params.path,
+          content: params.content
+        )
+      end
+
+      router.on_request("terminal/create", request_class: S::CreateTerminalRequest, optional: true) do |params|
+        handler.create_terminal(
+          session_id: params.session_id,
+          command: params.command,
+          args: params.args,
+          cwd: params.cwd,
+          env: params.env
+        )
+      end
+
+      router.on_request("terminal/output", request_class: S::TerminalOutputRequest, optional: true) do |params|
+        handler.terminal_output(
+          session_id: params.session_id,
+          terminal_id: params.terminal_id
+        )
+      end
+
+      router.on_request("terminal/release", request_class: S::ReleaseTerminalRequest, optional: true) do |params|
+        handler.release_terminal(
+          session_id: params.session_id,
+          terminal_id: params.terminal_id
+        )
+      end
+
+      router.on_request("terminal/wait_for_exit", request_class: S::WaitForTerminalExitRequest, optional: true) do |params|
+        handler.wait_for_terminal_exit(
+          session_id: params.session_id,
+          terminal_id: params.terminal_id
+        )
+      end
+
+      router.on_request("terminal/kill", request_class: S::KillTerminalCommandRequest, optional: true) do |params|
+        handler.kill_terminal(
+          session_id: params.session_id,
+          terminal_id: params.terminal_id
+        )
+      end
+
+      router.on_ext_method { |method, params| handler.ext_method(method, params) }
+      router.on_ext_notification { |method, params| handler.ext_notification(method, params) }
+
+      router
+    end
+  end
+end

data/lib/agent_client_protocol/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module ClientInterface
+    def on_connect(conn)
+      raise NotImplementedError, "#{self.class}#on_connect"
+    end
+
+    def session_update(session_id:, update:, **)
+      nil
+    end
+
+    def request_permission(session_id:, tool_call:, options:, **)
+      raise NotImplementedError, "#{self.class}#request_permission"
+    end
+
+    def read_text_file(session_id:, path:, line: nil, limit: nil, **)
+      raise RequestError.method_not_found("fs/read_text_file")
+    end
+
+    def write_text_file(session_id:, path:, content:, **)
+      raise RequestError.method_not_found("fs/write_text_file")
+    end
+
+    def create_terminal(session_id:, command:, args: nil, cwd: nil, env: nil, **)
+      raise RequestError.method_not_found("terminal/create")
+    end
+
+    def terminal_output(session_id:, terminal_id:, **)
+      raise RequestError.method_not_found("terminal/output")
+    end
+
+    def release_terminal(session_id:, terminal_id:, **)
+      raise RequestError.method_not_found("terminal/release")
+    end
+
+    def wait_for_terminal_exit(session_id:, terminal_id:, **)
+      raise RequestError.method_not_found("terminal/wait_for_exit")
+    end
+
+    def kill_terminal(session_id:, terminal_id:, **)
+      raise RequestError.method_not_found("terminal/kill")
+    end
+
+    def ext_method(method, params)
+      raise RequestError.method_not_found(method)
+    end
+
+    def ext_notification(method, params)
+      nil
+    end
+  end
+end