acp_sdk_async 0.2.0 → 0.3.0

data/lib/acp/contrib/session_state.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "../schema"
+require_relative "tool_calls"
+
+module ACP
+  module Contrib
+    class SessionNotificationMismatchError < ArgumentError
+      def initialize(expected, actual)
+        super("SessionAccumulator received notification for #{actual}, expected #{expected}")
+      end
+    end
+
+    class SessionSnapshotUnavailableError < RuntimeError
+      def initialize
+        super("SessionAccumulator has not processed any notifications yet")
+      end
+    end
+
+    # Immutable view of a tool call in the session.
+    class ToolCallView
+      attr_reader :tool_call_id, :title, :kind, :status,
+                  :content, :locations, :raw_input, :raw_output
+
+      def initialize(tool_call_id:, title:, kind:, status:,
+                     content:, locations:, raw_input:, raw_output:)
+        @tool_call_id = tool_call_id
+        @title = title
+        @kind = kind
+        @status = status
+        @content = content&.freeze
+        @locations = locations&.freeze
+        @raw_input = raw_input
+        @raw_output = raw_output
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && to_h == other.to_h
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      def to_h
+        {
+          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
+    end
+
+    # Aggregated immutable snapshot of the most recent session state.
+    class SessionSnapshot
+      attr_reader :session_id, :tool_calls, :plan_entries, :current_mode_id,
+                  :available_commands, :user_messages, :agent_messages, :agent_thoughts
+
+      def initialize(session_id:, tool_calls:, plan_entries:, current_mode_id:,
+                     available_commands:, user_messages:, agent_messages:, agent_thoughts:)
+        @session_id = session_id
+        @tool_calls = tool_calls.freeze
+        @plan_entries = plan_entries.freeze
+        @current_mode_id = current_mode_id
+        @available_commands = available_commands.freeze
+        @user_messages = user_messages.freeze
+        @agent_messages = agent_messages.freeze
+        @agent_thoughts = agent_thoughts.freeze
+        freeze
+      end
+    end
+
+    class MutableToolCallState
+      attr_reader :tool_call_id
+
+      def initialize(tool_call_id)
+        @tool_call_id = tool_call_id
+        @title = nil
+        @kind = nil
+        @status = nil
+        @content = nil
+        @locations = nil
+        @raw_input = nil
+        @raw_output = nil
+      end
+
+      def apply_start(update)
+        @title = update.title
+        @kind = update.kind
+        @status = update.status
+        @content = Contrib.copy_model_list(update.content)
+        @locations = Contrib.copy_model_list(update.locations)
+        @raw_input = update.raw_input
+        @raw_output = update.raw_output
+      end
+
+      def apply_progress(update)
+        @title = update.title unless update.title.nil?
+        @kind = update.kind unless update.kind.nil?
+        @status = update.status unless update.status.nil?
+        @content = Contrib.copy_model_list(update.content) unless update.content.nil?
+        @locations = Contrib.copy_model_list(update.locations) unless update.locations.nil?
+        @raw_input = update.raw_input unless update.raw_input.nil?
+        @raw_output = update.raw_output unless update.raw_output.nil?
+      end
+
+      def snapshot
+        ToolCallView.new(
+          tool_call_id: @tool_call_id,
+          title: @title,
+          kind: @kind,
+          status: @status,
+          content: @content&.map { |item| Contrib.deep_copy_model(item) },
+          locations: @locations&.map { |loc| Contrib.deep_copy_model(loc) },
+          raw_input: @raw_input,
+          raw_output: @raw_output
+        )
+      end
+    end
+
+    # Merges SessionNotification objects into a session snapshot.
+    # Experimental: APIs may change while feedback is gathered.
+    class SessionAccumulator
+      attr_reader :session_id
+
+      def initialize(auto_reset_on_session_change: true)
+        @auto_reset = auto_reset_on_session_change
+        @session_id = nil
+        @tool_calls = {}
+        @plan_entries = []
+        @current_mode_id = nil
+        @available_commands = []
+        @user_messages = []
+        @agent_messages = []
+        @agent_thoughts = []
+        @subscribers = []
+      end
+
+      def reset
+        @session_id = nil
+        @tool_calls.clear
+        @plan_entries.clear
+        @current_mode_id = nil
+        @available_commands.clear
+        @user_messages.clear
+        @agent_messages.clear
+        @agent_thoughts.clear
+      end
+
+      # Registers a callback invoked with (snapshot, notification) after
+      # every apply. Returns an unsubscribe lambda.
+      def subscribe(&callback)
+        @subscribers << callback
+        -> { @subscribers.delete(callback) }
+      end
+
+      def apply(notification)
+        ensure_session(notification)
+        apply_update(notification.update)
+        snap = snapshot
+        @subscribers.dup.each { |callback| callback.call(snap, notification) }
+        snap
+      end
+
+      def snapshot
+        raise SessionSnapshotUnavailableError if @session_id.nil?
+
+        SessionSnapshot.new(
+          session_id: @session_id,
+          tool_calls: @tool_calls.transform_values(&:snapshot),
+          plan_entries: @plan_entries.map { |entry| Contrib.deep_copy_model(entry) },
+          current_mode_id: @current_mode_id,
+          available_commands: @available_commands.map { |command| Contrib.deep_copy_model(command) },
+          user_messages: @user_messages.map { |message| Contrib.deep_copy_model(message) },
+          agent_messages: @agent_messages.map { |message| Contrib.deep_copy_model(message) },
+          agent_thoughts: @agent_thoughts.map { |message| Contrib.deep_copy_model(message) }
+        )
+      end
+
+      private
+
+      def ensure_session(notification)
+        if @session_id.nil?
+          @session_id = notification.session_id
+          return
+        end
+        handle_session_change(notification.session_id) if notification.session_id != @session_id
+      end
+
+      def handle_session_change(session_id)
+        if @session_id.nil?
+          @session_id = session_id
+          return
+        end
+        raise SessionNotificationMismatchError.new(@session_id, session_id) unless @auto_reset
+
+        reset
+        @session_id = session_id
+      end
+
+      def apply_update(update)
+        case update
+        when Schema::ToolCallStart
+          state_for(update.tool_call_id).apply_start(update)
+        when Schema::ToolCallProgress
+          state_for(update.tool_call_id).apply_progress(update)
+        when Schema::AgentPlanUpdate
+          @plan_entries = Contrib.copy_model_list(update.entries) || []
+        when Schema::CurrentModeUpdate
+          @current_mode_id = update.current_mode_id
+        when Schema::AvailableCommandsUpdate
+          @available_commands = Contrib.copy_model_list(update.available_commands) || []
+        when Schema::UserMessageChunk
+          @user_messages << Contrib.deep_copy_model(update)
+        when Schema::AgentMessageChunk
+          @agent_messages << Contrib.deep_copy_model(update)
+        when Schema::AgentThoughtChunk
+          @agent_thoughts << Contrib.deep_copy_model(update)
+        end
+      end
+
+      def state_for(tool_call_id)
+        @tool_calls[tool_call_id] ||= MutableToolCallState.new(tool_call_id)
+      end
+    end
+  end
+end

data/lib/acp/contrib/tool_calls.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "../schema"
+
+module ACP
+  module Contrib
+    # Sentinel for optional parameters. Use `equal?` to test for it; never serialize it.
+    UNSET = Object.new.freeze
+
+    class MissingToolCallTitleError < ArgumentError
+      def initialize
+        super("title must be set before sending a ToolCallStart")
+      end
+    end
+
+    class UnknownToolCallError < KeyError
+      attr_reader :external_id
+
+      def initialize(external_id)
+        @external_id = external_id
+        super("Unknown tool call id: #{external_id}")
+      end
+    end
+
+    def self.deep_copy_model(value)
+      Marshal.load(Marshal.dump(value))
+    end
+
+    def self.copy_model_list(items)
+      return nil if items.nil?
+
+      items.map { |item| deep_copy_model(item) }
+    end
+
+    # Immutable view of a tracked tool call.
+    class TrackedToolCallView
+      attr_reader :tool_call_id, :title, :name, :kind, :status,
+                  :content, :locations, :raw_input, :raw_output
+
+      def initialize(tool_call_id:, title:, name:, kind:, status:,
+                     content:, locations:, raw_input:, raw_output:)
+        @tool_call_id = tool_call_id
+        @title = title
+        @name = name
+        @kind = kind
+        @status = status
+        @content = content&.freeze
+        @locations = locations&.freeze
+        @raw_input = raw_input
+        @raw_output = raw_output
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && to_h == other.to_h
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      def to_h
+        {
+          tool_call_id: @tool_call_id, title: @title, name: @name,
+          kind: @kind, status: @status, content: @content,
+          locations: @locations, raw_input: @raw_input, raw_output: @raw_output
+        }
+      end
+    end
+
+    class TrackedToolCall
+      attr_reader :tool_call_id
+
+      def initialize(tool_call_id:, title: nil, name: nil, kind: nil, status: nil,
+                     content: nil, locations: nil, raw_input: nil, raw_output: nil)
+        @tool_call_id = tool_call_id
+        @title = title
+        @name = name
+        @kind = kind
+        @status = status
+        @content = Contrib.copy_model_list(content)
+        @locations = Contrib.copy_model_list(locations)
+        @raw_input = raw_input
+        @raw_output = raw_output
+        @stream_buffer = nil
+      end
+
+      def to_view
+        TrackedToolCallView.new(
+          tool_call_id: @tool_call_id,
+          title: @title,
+          name: @name,
+          kind: @kind,
+          status: @status,
+          content: @content&.map { |item| Contrib.deep_copy_model(item) },
+          locations: @locations&.map { |loc| Contrib.deep_copy_model(loc) },
+          raw_input: @raw_input,
+          raw_output: @raw_output
+        )
+      end
+
+      def to_tool_call_model
+        Schema::ToolCallUpdate.new(
+          tool_call_id: @tool_call_id,
+          title: @title,
+          name: @name,
+          kind: @kind,
+          status: @status,
+          content: Contrib.copy_model_list(@content),
+          locations: Contrib.copy_model_list(@locations),
+          raw_input: @raw_input,
+          raw_output: @raw_output
+        )
+      end
+
+      def to_start_model
+        raise MissingToolCallTitleError if @title.nil?
+
+        Schema::ToolCallStart.new(
+          tool_call_id: @tool_call_id,
+          title: @title,
+          name: @name,
+          kind: @kind,
+          status: @status,
+          content: Contrib.copy_model_list(@content),
+          locations: Contrib.copy_model_list(@locations),
+          raw_input: @raw_input,
+          raw_output: @raw_output
+        )
+      end
+
+      def update(title: UNSET, name: UNSET, kind: UNSET, status: UNSET,
+                 content: UNSET, locations: UNSET, raw_input: UNSET, raw_output: UNSET)
+        kwargs = { tool_call_id: @tool_call_id }
+        unless title.equal?(UNSET)
+          @title = title
+          kwargs[:title] = @title
+        end
+        unless name.equal?(UNSET)
+          @name = name
+          kwargs[:name] = @name
+        end
+        unless kind.equal?(UNSET)
+          @kind = kind
+          kwargs[:kind] = @kind
+        end
+        unless status.equal?(UNSET)
+          @status = status
+          kwargs[:status] = @status
+        end
+        unless content.equal?(UNSET)
+          @content = Contrib.copy_model_list(content)
+          kwargs[:content] = Contrib.copy_model_list(content)
+        end
+        unless locations.equal?(UNSET)
+          @locations = Contrib.copy_model_list(locations)
+          kwargs[:locations] = Contrib.copy_model_list(locations)
+        end
+        unless raw_input.equal?(UNSET)
+          @raw_input = raw_input
+          kwargs[:raw_input] = @raw_input
+        end
+        unless raw_output.equal?(UNSET)
+          @raw_output = raw_output
+          kwargs[:raw_output] = @raw_output
+        end
+        Schema::ToolCallProgress.new(**kwargs)
+      end
+
+      def append_stream_text(text, title: UNSET, status: UNSET)
+        @stream_buffer = "#{@stream_buffer}#{text}"
+        content = [Schema::ContentToolCallContent.new(content: Schema::TextContentBlock.new(text: @stream_buffer))]
+        update(title: title, status: status, content: content)
+      end
+    end
+
+    # Utility for generating ACP tool call updates on the agent side.
+    class ToolCallTracker
+      def initialize(id_factory: nil)
+        @id_factory = id_factory || -> { SecureRandom.hex(16) }
+        @calls = {}
+      end
+
+      def start(external_id, title:, name: nil, kind: nil, status: "in_progress",
+                content: nil, locations: nil, raw_input: nil, raw_output: nil)
+        state = TrackedToolCall.new(
+          tool_call_id: @id_factory.call,
+          title: title,
+          name: name,
+          kind: kind,
+          status: status,
+          content: content,
+          locations: locations,
+          raw_input: raw_input,
+          raw_output: raw_output
+        )
+        @calls[external_id] = state
+        state.to_start_model
+      end
+
+      def progress(external_id, title: UNSET, name: UNSET, kind: UNSET, status: UNSET,
+                   content: UNSET, locations: UNSET, raw_input: UNSET, raw_output: UNSET)
+        require_call(external_id).update(
+          title: title, name: name, 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: UNSET, status: UNSET)
+        require_call(external_id).append_stream_text(text, title: title, status: status)
+      end
+
+      def forget(external_id)
+        @calls.delete(external_id)
+      end
+
+      def tracked?(external_id)
+        @calls.key?(external_id)
+      end
+
+      def view(external_id)
+        require_call(external_id).to_view
+      end
+
+      def tool_call_model(external_id)
+        require_call(external_id).to_tool_call_model
+      end
+
+      private
+
+      def require_call(external_id)
+        @calls.fetch(external_id) { raise UnknownToolCallError, external_id }
+      end
+    end
+  end
+end

data/lib/acp/exceptions.rb

@@ -12,14 +12,14 @@ module ACP
       @data = data
     end
 
-    def self.parse_error(data = nil)        = new(-32700, "Parse error", data)
-    def self.invalid_request(data = nil)     = new(-32600, "Invalid request", data)
-    def self.method_not_found(method)        = new(-32601, "Method not found", { "method" => method })
-    def self.invalid_params(data = nil)      = new(-32602, "Invalid params", data)
-    def self.internal_error(data = nil)      = new(-32603, "Internal error", data)
-    def self.request_cancelled(data = nil)   = new(-32800, "Request cancelled", data)
-    def self.auth_required(data = nil)       = new(-32000, "Authentication required", data)
-    def self.resource_not_found(uri = nil)   = new(-32002, "Resource not found", uri ? { "uri" => uri } : nil)
+    def self.parse_error(data = nil) = new(-32700, "Parse error", data)
+    def self.invalid_request(data = nil) = new(-32600, "Invalid request", data)
+    def self.method_not_found(method) = new(-32601, "Method not found", { "method" => method })
+    def self.invalid_params(data = nil) = new(-32602, "Invalid params", data)
+    def self.internal_error(data = nil) = new(-32603, "Internal error", data)
+    def self.request_cancelled(data = nil) = new(-32800, "Request cancelled", data)
+    def self.auth_required(data = nil) = new(-32000, "Authentication required", data)
+    def self.resource_not_found(uri = nil) = new(-32002, "Resource not found", uri ? { "uri" => uri } : nil)
 
     def to_error_obj
       { "code" => @code, "message" => message, "data" => @data }

data/lib/acp/router.rb

@@ -24,7 +24,10 @@ module ACP
         raise RequestError.method_not_found(@method)
       end
 
-      argument = @model ? @model.coerce(params.nil? ? {} : params) : params
+      # Do NOT coerce nil -> {}: missing params must fail validation
+      # (invalid_params) instead of being silently replaced.
+      # Extension routes handle nil themselves (nil -> {} for wire compat).
+      argument = @model ? @model.coerce(params) : params
       result = @handler.call(argument)
       return result unless @kind == :request && @adapt_result
 
@@ -54,25 +57,25 @@ module ACP
     def route_request(method, model, target, *names, optional: false, default_result: nil, normalize: false)
       handler = resolve_handler(target, names)
       add_route(Route.new(
-        method: method,
-        handler: handler,
-        kind: :request,
-        model: model,
-        optional: optional,
-        default_result: default_result,
-        adapt_result: normalize ? NORMALIZE_RESULT : nil
-      ))
+                  method: method,
+                  handler: handler,
+                  kind: :request,
+                  model: model,
+                  optional: optional,
+                  default_result: default_result,
+                  adapt_result: normalize ? NORMALIZE_RESULT : nil
+                ))
     end
 
     def route_notification(method, model, target, *names)
       handler = resolve_handler(target, names)
       add_route(Route.new(
-        method: method,
-        handler: handler,
-        kind: :notification,
-        model: model,
-        optional: true
-      ))
+                  method: method,
+                  handler: handler,
+                  kind: :notification,
+                  model: model,
+                  optional: true
+                ))
     end
 
     def on_extension_request(&block)