acp_ruby 0.1.0

data/lib/agent_client_protocol/connection.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+require "async"
+
+module AgentClientProtocol
+  class Connection
+    JSONRPC_VERSION = "2.0"
+
+    attr_reader :reader, :writer
+
+    def initialize(reader:, writer:, handler:)
+      @reader = reader
+      @writer = writer
+      @handler = handler
+      @next_id = 0
+      @pending = {} # id -> Async::Promise
+      @mutex = Mutex.new
+      @closed = false
+    end
+
+    def send_request(method, params = nil)
+      id = next_id
+      variable = Async::Promise.new
+
+      @mutex.synchronize { @pending[id] = variable }
+
+      msg = {"jsonrpc" => JSONRPC_VERSION, "id" => id, "method" => method}
+      msg["params"] = params if params
+      @writer.write(msg)
+
+      result = variable.wait
+      if result.is_a?(Hash) && result.key?("__error__")
+        raise RequestError.from_hash(result["__error__"])
+      end
+      result
+    end
+
+    def send_notification(method, params = nil)
+      msg = {"jsonrpc" => JSONRPC_VERSION, "method" => method}
+      msg["params"] = params if params
+      @writer.write(msg)
+    end
+
+    def listen
+      @reader.each do |message|
+        process_message(message)
+      end
+    rescue IOError, Errno::EPIPE
+      # Connection closed
+    ensure
+      close
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+
+      # Reject all pending requests
+      @mutex.synchronize do
+        @pending.each_value do |var|
+          var.resolve({"__error__" => {"code" => -32603, "message" => "Connection closed"}}) unless var.resolved?
+        end
+        @pending.clear
+      end
+
+      @reader.close
+      @writer.close
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def next_id
+      @mutex.synchronize { @next_id += 1 }
+    end
+
+    def process_message(message)
+      has_method = message.key?("method")
+      has_id = message.key?("id")
+
+      if has_method && has_id
+        handle_request(message)
+      elsif has_method
+        handle_notification(message)
+      elsif has_id
+        handle_response(message)
+      end
+    end
+
+    def handle_request(message)
+      id = message["id"]
+      method = message["method"]
+      params = message["params"]
+
+      begin
+        result = @handler.call(method, params, false)
+        send_response(id, result: result)
+      rescue RequestError => e
+        send_response(id, error: e.to_h)
+      rescue => e
+        send_response(id, error: RequestError.internal_error(e.message).to_h)
+      end
+    end
+
+    def handle_notification(message)
+      method = message["method"]
+      params = message["params"]
+
+      @handler.call(method, params, true)
+    rescue RequestError
+      # Notifications don't send error responses
+    rescue => e
+      # Log but don't propagate — notifications are fire-and-forget
+      $stderr.puts("ACP notification handler error: #{e.message}") if $DEBUG
+    end
+
+    def handle_response(message)
+      id = message["id"]
+      variable = @mutex.synchronize { @pending.delete(id) }
+      return unless variable
+
+      if message.key?("error")
+        variable.resolve({"__error__" => message["error"]})
+      else
+        variable.resolve(message["result"])
+      end
+    end
+
+    def send_response(id, result: nil, error: nil)
+      msg = {"jsonrpc" => JSONRPC_VERSION, "id" => id}
+      if error
+        msg["error"] = error
+      else
+        msg["result"] = result
+      end
+      @writer.write(msg)
+    end
+  end
+end

data/lib/agent_client_protocol/contrib/permission_broker.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Contrib
+    class PermissionBroker
+      def initialize(requester:, tracker: nil)
+        @requester = requester
+        @tracker = tracker
+      end
+
+      def request_for(external_id, session_id:, description: nil, options: nil, content: nil, tool_call: nil)
+        tc = tool_call
+        if tc.nil? && @tracker
+          tc = @tracker.tool_call_model(external_id)
+        end
+        tc ||= Schema::ToolCallUpdate.new(
+          tool_call_id: external_id,
+          title: description || external_id
+        )
+
+        opts = options || default_permission_options
+
+        @requester.call(
+          session_id: session_id,
+          tool_call: tc,
+          options: opts
+        )
+      end
+
+      def self.default_permission_options
+        [
+          Schema::PermissionOption.new(
+            option_id: "approve",
+            name: "Approve",
+            kind: Schema::PermissionOptionKind::ALLOW_ONCE
+          ),
+          Schema::PermissionOption.new(
+            option_id: "approve_session",
+            name: "Approve for session",
+            kind: Schema::PermissionOptionKind::ALLOW_ALWAYS
+          ),
+          Schema::PermissionOption.new(
+            option_id: "reject",
+            name: "Reject",
+            kind: Schema::PermissionOptionKind::REJECT_ONCE
+          )
+        ]
+      end
+
+      private
+
+      def default_permission_options
+        self.class.default_permission_options
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/contrib/session_accumulator.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Contrib
+    class SessionAccumulator
+      SessionSnapshot = Struct.new(
+        :session_id, :tool_calls, :plan_entries, :current_mode_id,
+        :available_commands, :user_messages, :agent_messages, :agent_thoughts,
+        :config_options,
+        keyword_init: true
+      ) do
+        def freeze
+          tool_calls&.freeze
+          plan_entries&.freeze
+          available_commands&.freeze
+          user_messages&.freeze
+          agent_messages&.freeze
+          agent_thoughts&.freeze
+          config_options&.freeze
+          super
+        end
+      end
+
+      def initialize
+        reset
+        @subscribers = []
+      end
+
+      def reset
+        @session_id = nil
+        @tool_calls = {}
+        @plan_entries = []
+        @current_mode_id = nil
+        @available_commands = []
+        @user_messages = []
+        @agent_messages = []
+        @agent_thoughts = []
+        @config_options = []
+      end
+
+      def apply(notification)
+        notif = normalize(notification)
+        session_id = notif[:session_id]
+        update = notif[:update]
+
+        # Reset on session change
+        if @session_id && @session_id != session_id
+          reset
+        end
+        @session_id = session_id
+
+        apply_update(update)
+
+        snap = snapshot
+        @subscribers.each { |cb| cb.call(snap, notification) }
+        snap
+      end
+
+      def snapshot
+        SessionSnapshot.new(
+          session_id: @session_id,
+          tool_calls: @tool_calls.dup,
+          plan_entries: @plan_entries.dup,
+          current_mode_id: @current_mode_id,
+          available_commands: @available_commands.dup,
+          user_messages: @user_messages.dup,
+          agent_messages: @agent_messages.dup,
+          agent_thoughts: @agent_thoughts.dup,
+          config_options: @config_options.dup
+        ).freeze
+      end
+
+      def subscribe(&block)
+        @subscribers << block
+      end
+
+      private
+
+      def normalize(notification)
+        case notification
+        when Schema::SessionNotification
+          {session_id: notification.session_id, update: notification.update}
+        when Hash
+          sid = notification["sessionId"] || notification[:session_id]
+          upd = notification["update"] || notification[:update]
+          {session_id: sid, update: upd}
+        else
+          {session_id: notification.session_id, update: notification.update}
+        end
+      end
+
+      def apply_update(update)
+        return unless update
+
+        session_update_type = case update
+                              when TaggedUpdate
+                                update.tag
+                              when Hash
+                                update["sessionUpdate"] || update[:session_update]
+                              when Schema::BaseModel
+                                update.to_h["sessionUpdate"]
+                              end
+
+        case session_update_type
+        when "user_message_chunk"
+          content = extract_content(update)
+          @user_messages << content if content
+        when "agent_message_chunk"
+          content = extract_content(update)
+          @agent_messages << content if content
+        when "agent_thought_chunk"
+          content = extract_content(update)
+          @agent_thoughts << content if content
+        when "tool_call"
+          tc_id = extract_field(update, "toolCallId", :tool_call_id)
+          @tool_calls[tc_id] = update if tc_id
+        when "tool_call_update"
+          tc_id = extract_field(update, "toolCallId", :tool_call_id)
+          @tool_calls[tc_id] = merge_tool_call(@tool_calls[tc_id], update) if tc_id
+        when "plan"
+          entries = extract_field(update, "entries", :entries)
+          @plan_entries = entries || []
+        when "available_commands_update"
+          commands = extract_field(update, "availableCommands", :available_commands)
+          @available_commands = commands || []
+        when "current_mode_update"
+          @current_mode_id = extract_field(update, "currentModeId", :current_mode_id)
+        when "config_option_update"
+          options = extract_field(update, "configOptions", :config_options)
+          @config_options = options || []
+        end
+      end
+
+      def extract_content(update)
+        case update
+        when Hash
+          update["content"] || update[:content]
+        when Schema::ContentChunk
+          update.content
+        else
+          update.respond_to?(:content) ? update.content : nil
+        end
+      end
+
+      def extract_field(update, json_key, ruby_key)
+        case update
+        when Hash
+          update[json_key] || update[ruby_key]
+        else
+          update.respond_to?(ruby_key) ? update.send(ruby_key) : nil
+        end
+      end
+
+      def merge_tool_call(existing, update)
+        # Just replace with the update — the update contains the latest state
+        update
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/contrib/tool_call_tracker.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module AgentClientProtocol
+  module Contrib
+    class ToolCallTracker
+      TrackedToolCallView = Struct.new(
+        :external_id, :tool_call_id, :title, :kind, :status,
+        :content, :locations, :raw_input, :raw_output, :stream_text,
+        keyword_init: true
+      )
+
+      def initialize(id_factory: -> { SecureRandom.hex(16) })
+        @id_factory = id_factory
+        @tracked = {} # external_id -> TrackedToolCallView
+      end
+
+      def start(external_id, title:, kind: nil, status: nil, content: nil, locations: nil, raw_input: nil, raw_output: nil)
+        tool_call_id = @id_factory.call
+        view = TrackedToolCallView.new(
+          external_id: external_id,
+          tool_call_id: tool_call_id,
+          title: title,
+          kind: kind,
+          status: status || Schema::ToolCallStatus::PENDING,
+          content: content || [],
+          locations: locations || [],
+          raw_input: raw_input,
+          raw_output: raw_output,
+          stream_text: ""
+        )
+        @tracked[external_id] = view
+
+        Schema::ToolCall.new(
+          tool_call_id: tool_call_id,
+          title: title,
+          kind: kind,
+          status: status || Schema::ToolCallStatus::PENDING,
+          content: content,
+          locations: locations,
+          raw_input: raw_input,
+          raw_output: raw_output
+        )
+      end
+
+      def progress(external_id, title: nil, kind: nil, status: nil, content: nil, locations: nil, raw_input: nil, raw_output: nil)
+        view = @tracked[external_id]
+        raise ArgumentError, "Unknown tool call: #{external_id}" unless view
+
+        view.title = title if title
+        view.kind = kind if kind
+        view.status = status if status
+        view.content = content if content
+        view.locations = locations if locations
+        view.raw_input = raw_input if raw_input
+        view.raw_output = raw_output if raw_output
+
+        Schema::ToolCallUpdate.new(
+          tool_call_id: view.tool_call_id,
+          title: title,
+          kind: kind,
+          status: status,
+          content: content,
+          locations: locations,
+          raw_input: raw_input,
+          raw_output: raw_output
+        )
+      end
+
+      def append_stream_text(external_id, text, title: nil, status: nil)
+        view = @tracked[external_id]
+        raise ArgumentError, "Unknown tool call: #{external_id}" unless view
+
+        view.stream_text = (view.stream_text || "") + text
+        view.title = title if title
+        view.status = status if status
+
+        Schema::ToolCallUpdate.new(
+          tool_call_id: view.tool_call_id,
+          title: title,
+          status: status,
+          raw_output: view.stream_text
+        )
+      end
+
+      def view(external_id)
+        view = @tracked[external_id]
+        raise ArgumentError, "Unknown tool call: #{external_id}" unless view
+
+        TrackedToolCallView.new(**view.to_h)
+      end
+
+      def tool_call_model(external_id)
+        v = @tracked[external_id]
+        raise ArgumentError, "Unknown tool call: #{external_id}" unless v
+
+        Schema::ToolCallUpdate.new(
+          tool_call_id: v.tool_call_id,
+          title: v.title,
+          kind: v.kind,
+          status: v.status,
+          content: v.content,
+          locations: v.locations,
+          raw_input: v.raw_input,
+          raw_output: v.raw_output
+        )
+      end
+
+      def forget(external_id)
+        @tracked.delete(external_id)
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  class RequestError < StandardError
+    attr_reader :code, :data
+
+    PARSE_ERROR        = -32700
+    INVALID_REQUEST    = -32600
+    METHOD_NOT_FOUND   = -32601
+    INVALID_PARAMS     = -32602
+    INTERNAL_ERROR     = -32603
+    AUTH_REQUIRED      = -32000
+    RESOURCE_NOT_FOUND = -32002
+
+    def initialize(code, message, data = nil)
+      @code = code
+      @data = data
+      super(message)
+    end
+
+    def to_h
+      h = {"code" => @code, "message" => message}
+      h["data"] = @data if @data
+      h
+    end
+
+    class << self
+      def parse_error(data = nil)        = new(PARSE_ERROR, "Parse error", data)
+      def invalid_request(data = nil)    = new(INVALID_REQUEST, "Invalid request", data)
+      def method_not_found(method)       = new(METHOD_NOT_FOUND, "Method not found", {"method" => method})
+      def invalid_params(data = nil)     = new(INVALID_PARAMS, "Invalid params", data)
+      def internal_error(data = nil)     = new(INTERNAL_ERROR, "Internal error", data)
+      def auth_required(data = nil)      = new(AUTH_REQUIRED, "Authentication required", data)
+      def resource_not_found(uri = nil)  = new(RESOURCE_NOT_FOUND, "Resource not found", uri ? {"uri" => uri} : nil)
+
+      def from_hash(hash)
+        new(hash["code"], hash["message"], hash["data"])
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/helpers.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Helpers
+    # --- Content blocks ---
+
+    def text_block(text)
+      Schema::TextContent.new(text: text)
+    end
+
+    def image_block(data, mime_type, uri: nil)
+      Schema::ImageContent.new(data: data, mime_type: mime_type, uri: uri)
+    end
+
+    def audio_block(data, mime_type)
+      Schema::AudioContent.new(data: data, mime_type: mime_type)
+    end
+
+    def resource_link_block(name:, uri:, mime_type: nil, size: nil, description: nil, title: nil)
+      Schema::ResourceLink.new(
+        name: name, uri: uri, mime_type: mime_type,
+        size: size, description: description, title: title
+      )
+    end
+
+    def embedded_text_resource(uri:, text:, mime_type: nil)
+      Schema::TextResourceContents.new(uri: uri, text: text, mime_type: mime_type)
+    end
+
+    def embedded_blob_resource(uri:, blob:, mime_type: nil)
+      Schema::BlobResourceContents.new(uri: uri, blob: blob, mime_type: mime_type)
+    end
+
+    def resource_block(resource)
+      Schema::EmbeddedResource.new(resource: resource)
+    end
+
+    # --- Tool call content ---
+
+    def tool_content(block)
+      Schema::Content.new(content: block)
+    end
+
+    def tool_diff_content(path, new_text, old_text: nil)
+      Schema::Diff.new(path: path, new_text: new_text, old_text: old_text)
+    end
+
+    def tool_terminal_ref(terminal_id)
+      Schema::Terminal.new(terminal_id: terminal_id)
+    end
+
+    # --- Session updates ---
+    # These return TaggedUpdate objects that include the sessionUpdate discriminator
+    # when serialized, matching the wire format.
+
+    def update_agent_message(content)
+      TaggedUpdate.new("agent_message_chunk", Schema::ContentChunk.new(content: content))
+    end
+
+    def update_agent_message_text(text)
+      update_agent_message(text_block(text))
+    end
+
+    def update_user_message(content)
+      TaggedUpdate.new("user_message_chunk", Schema::ContentChunk.new(content: content))
+    end
+
+    def update_user_message_text(text)
+      update_user_message(text_block(text))
+    end
+
+    def update_agent_thought(content)
+      TaggedUpdate.new("agent_thought_chunk", Schema::ContentChunk.new(content: content))
+    end
+
+    def update_agent_thought_text(text)
+      update_agent_thought(text_block(text))
+    end
+
+    def update_available_commands(commands)
+      TaggedUpdate.new("available_commands_update",
+        Schema::AvailableCommandsUpdate.new(available_commands: commands))
+    end
+
+    def update_current_mode(current_mode_id)
+      TaggedUpdate.new("current_mode_update",
+        Schema::CurrentModeUpdate.new(current_mode_id: current_mode_id))
+    end
+
+    def update_config_options(config_options)
+      TaggedUpdate.new("config_option_update",
+        Schema::ConfigOptionUpdate.new(config_options: config_options))
+    end
+
+    # --- Plans ---
+
+    def plan_entry(content, priority: Schema::PlanEntryPriority::MEDIUM, status: Schema::PlanEntryStatus::PENDING)
+      Schema::PlanEntry.new(content: content, priority: priority, status: status)
+    end
+
+    def update_plan(entries)
+      TaggedUpdate.new("plan", Schema::Plan.new(entries: entries))
+    end
+
+    # --- Tool calls ---
+
+    def start_tool_call(tool_call_id, title, kind: nil, status: nil, content: nil, locations: nil, raw_input: nil, raw_output: nil)
+      TaggedUpdate.new("tool_call", Schema::ToolCall.new(
+        tool_call_id: tool_call_id,
+        title: title,
+        kind: kind,
+        status: status,
+        content: content,
+        locations: locations,
+        raw_input: raw_input,
+        raw_output: raw_output
+      ))
+    end
+
+    def update_tool_call(tool_call_id, title: nil, kind: nil, status: nil, content: nil, locations: nil, raw_input: nil, raw_output: nil)
+      TaggedUpdate.new("tool_call_update", Schema::ToolCallUpdate.new(
+        tool_call_id: tool_call_id,
+        title: title,
+        kind: kind,
+        status: status,
+        content: content,
+        locations: locations,
+        raw_input: raw_input,
+        raw_output: raw_output
+      ))
+    end
+
+    # --- Notification wrapper ---
+
+    def session_notification(session_id, update)
+      Schema::SessionNotification.new(session_id: session_id, update: update)
+    end
+  end
+
+  # A session update tagged with its discriminator value.
+  # Serializes to include the "sessionUpdate" key in the wire format.
+  class TaggedUpdate
+    attr_reader :tag, :model
+
+    def initialize(tag, model)
+      @tag = tag
+      @model = model
+    end
+
+    def to_h
+      h = @model.is_a?(Schema::BaseModel) ? @model.to_h : @model
+      {"sessionUpdate" => @tag}.merge(h)
+    end
+
+    def to_json(*)
+      JSON.generate(to_h, *)
+    end
+
+    # Delegate attribute access to the underlying model
+    def respond_to_missing?(method, include_private = false)
+      @model.respond_to?(method, include_private) || super
+    end
+
+    def method_missing(method, ...)
+      if @model.respond_to?(method)
+        @model.send(method, ...)
+      else
+        super
+      end
+    end
+
+    def inspect
+      "#<TaggedUpdate tag=#{@tag.inspect} #{@model.inspect}>"
+    end
+  end
+end