acp-sdk 0.10.0 → 0.12.0

data/lib/acp/protocol.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ACP::Protocol
+  PROTOCOL_VERSION = 1 #: Integer
+
+  extend self
+
+  # @rbs capabilities: (ACP::Types::AgentCapabilities | ACP::Types::Unstable::AgentCapabilities | Hash[String, untyped])
+  # @rbs return: bool
+  def mcp_acp_advertised?(capabilities)
+    # The stable McpCapabilities has no acp field, so the gate can only read it
+    # when the caller opted in with `require 'acp/types/unstable'`.
+    return false unless ACP::Types.unstable_enabled?
+
+    mcp =
+      case capabilities
+      when ACP::Types::AgentCapabilities, ACP::Types::Unstable::AgentCapabilities
+        capabilities.mcp_capabilities #: ACP::Types::McpCapabilities | ACP::Types::Unstable::McpCapabilities?
+      when Hash
+        # The client's stable parse of the initialize reply drops acp, so
+        # mcpCapabilities is re-parsed from the raw hash with the unstable
+        # type. Only that sub-object: the other unstable fields arrive
+        # unvalidated and must not decide whether MCP is advertised.
+        raw = capabilities['mcpCapabilities']
+        ACP::Types::Unstable::McpCapabilities.from_h(raw) if raw.is_a?(Hash)
+      end
+    return false unless mcp.is_a?(ACP::Types::Unstable::McpCapabilities)
+
+    mcp.acp ? true : false
+  rescue ACP::Types::ParseError
+    false
+  end
+end

data/lib/acp/request_error.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# 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.
+# Named after the official SDKs' RequestError rather than the schema's Error.
 class ACP::RequestError
   PARSE_ERROR = -32_700 #: Integer
   INVALID_REQUEST = -32_600 #: Integer
@@ -38,6 +36,16 @@ class ACP::RequestError
     { 'code' => code, 'message' => message, 'data' => data }.compact
   end
 
+  CONNECTION_CLOSED = new(code: INTERNAL_ERROR, message: 'Connection closed') #: ACP::RequestError
+
+  # Identity rather than code and message: a live peer can answer with the
+  # same pair, and that refusal must not read as a closed connection.
+  #
+  # @rbs return: bool
+  def connection_closed?
+    equal?(CONNECTION_CLOSED)
+  end
+
   # @rbs return: ACP::RequestError
   def self.parse_error
     new(code: PARSE_ERROR, message: 'Parse error')
@@ -60,9 +68,8 @@ class ACP::RequestError
     new(code: INVALID_PARAMS, message: 'Invalid params', data: errors && { errors: errors })
   end
 
-  # The method-not-found code for a method the client's capabilities do not
-  # advertise, with a message that names the capability so it can be told
-  # apart from an unknown method.
+  # The message names the capability so the refusal can be told apart from an
+  # unknown method, though both use the -32601 code.
   #
   # @rbs capability: String
   # @rbs return: ACP::RequestError
@@ -70,11 +77,9 @@ class ACP::RequestError
     new(code: METHOD_NOT_FOUND, message: "Client does not advertise #{capability}")
   end
 
-  # The invalid-params code for a request whose mode the client's
-  # capabilities do not advertise, with a message that names the mode so it
-  # can be told apart from malformed params. The spec gives elicitation a
-  # mode in its params, so an unadvertised one is invalid params rather than
-  # method not found.
+  # The message names the mode so the refusal can be told apart from malformed
+  # params. The spec gives elicitation a mode in its params, so an unadvertised
+  # one is invalid params rather than method not found.
   #
   # @rbs mode: String
   # @rbs return: ACP::RequestError
@@ -82,10 +87,6 @@ class ACP::RequestError
     new(code: INVALID_PARAMS, message: "Client does not advertise #{mode}")
   end
 
-  # unadvertised names a capability of the client's, this one a capability of
-  # the agent's: the same method-not-found code, with a message naming which
-  # side's advertisement is missing.
-  #
   # @rbs capability: String
   # @rbs return: ACP::RequestError
   def self.unadvertised_agent(capability)
@@ -106,8 +107,7 @@ class ACP::RequestError
     new(code: INTERNAL_ERROR, message: 'Invalid response', data: response)
   end
 
-  # A local refusal of an initialize reply that names a version the SDK does
-  # not speak; the message names both versions so logs can tell it from a
+  # The message names both versions so logs can tell this local refusal from a
   # peer's error.
   #
   # @rbs requested: Integer

data/lib/acp/transport/cancellation.rb

@@ -1,15 +1,8 @@
 # frozen_string_literal: true
 
-# Whether the peer cancelled one request. The transport creates one per served
-# request, marks it when the peer's $/cancel_request arrives, and hands it to
-# the serving thread, whose handler can observe it and end the request early.
 class ACP::Transport::Cancellation
   KEY = :acp_serving_cancellation #: Symbol
 
-  # Connections read this to expose the serving state to their handlers and
-  # write it to carry serving identity onto a thread they spawn; nil off a
-  # serve thread.
-  #
   # @rbs return: ACP::Transport::Cancellation?
   def self.current
     Thread.current[KEY] #: ACP::Transport::Cancellation?

data/lib/acp/transport/reply.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# 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::Stdio::_ToH

data/lib/acp/transport/stderr_logger.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-# The default sink for dropped messages and swallowed errors: the spec
-# sanctions agents logging to stderr.
+# The spec sanctions agents logging to stderr.
 class ACP::Transport::StderrLogger
   # @rbs message: String
   # @rbs return: void

data/lib/acp/transport/stdio/serving.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class ACP::Transport::Stdio::Serving
+  # @dynamic id
+  attr_reader :id #: untyped
+
+  # @dynamic cancellation
+  attr_reader :cancellation #: ACP::Transport::Cancellation
+
+  # @rbs id: untyped
+  # @rbs cancellation: ACP::Transport::Cancellation
+  # @rbs return: void
+  def initialize(id:, cancellation:)
+    @id = id
+    @cancellation = cancellation
+    freeze
+  end
+end

data/lib/acp/transport/stdio.rb

@@ -2,25 +2,22 @@
 
 require 'json'
 
-# JSON-RPC 2.0 over newline-delimited JSON on an IO pair. A reader thread
-# dispatches inbound messages while outbound requests are pending, and each
-# inbound request is served on its own thread, so a handler can make an
-# outbound request mid-turn and still see notifications (e.g. session/cancel)
-# that arrive meanwhile.
+# A reader thread dispatches inbound messages while outbound requests are
+# pending, and each inbound request is served on its own thread, so a handler
+# can make an outbound request mid-turn and still see notifications (e.g.
+# session/cancel) that arrive meanwhile.
 class ACP::Transport::Stdio
   # @rbs @input: _Reader
   # @rbs @output: _Writer
   # @rbs @write_lock: Thread::Mutex
   # @rbs @lock: Thread::Mutex
   # @rbs @pending: Hash[untyped, Thread::Queue]
-  # @rbs @serving: Hash[untyped, ACP::Transport::Cancellation]
+  # @rbs @serving: Hash[Thread, ACP::Transport::Stdio::Serving]
   # @rbs @next_id: Integer
   # @rbs @closed: bool
   # @rbs @logger: ACP::Transport::_Logger
 
-  CONNECTION_CLOSED = ACP::RequestError.new(
-    code: ACP::RequestError::INTERNAL_ERROR, message: 'Connection closed'
-  ) #: ACP::RequestError
+  CONNECTION_CLOSED = ACP::RequestError::CONNECTION_CLOSED #: ACP::RequestError
 
   # @rbs input: _Reader
   # @rbs output: _Writer
@@ -38,8 +35,12 @@ class ACP::Transport::Stdio
     @logger = logger
   end
 
-  # Returns the reader thread, which ends at EOF on input after releasing any
-  # pending outbound requests.
+  # Joining the returned thread does not wait for the requests still being
+  # served. EOF cancels none of them (only the peer's $/cancel_request does):
+  # each handler runs to completion and its reply is still written, to be
+  # warned and dropped if the peer is gone. A caller blocked in #request, a
+  # handler waiting on its own request included, is released with
+  # CONNECTION_CLOSED.
   #
   # @rbs requests: Hash[String, _Handler]
   # @rbs notifications: Hash[String, _NotificationHandler]
@@ -55,14 +56,16 @@ class ACP::Transport::Stdio
 
   # @rbs method: String
   # @rbs params: untyped
-  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  # @rbs return: untyped
   def request(method, params = nil)
     queue = Thread::Queue.new
     id = register(queue)
     return CONNECTION_CLOSED unless id
 
     write({ 'jsonrpc' => '2.0', 'id' => id, 'method' => method, 'params' => params }.compact)
-    queue.pop || CONNECTION_CLOSED
+    result = queue.pop
+    # A null result pops nil just as a closed queue does.
+    queue.closed? ? CONNECTION_CLOSED : result
   end
 
   # @rbs method: String
@@ -90,16 +93,24 @@ class ACP::Transport::Stdio
     @lock.synchronize { @pending.keys }.each { |id| cancel(id) }
   end
 
-  # The cancellation of the request the calling thread is serving, or nil off
-  # a serve thread. A handler observes the peer's $/cancel_request through it
-  # and can end early with ACP::RequestError.request_cancelled; whatever it
-  # returns, the transport sends exactly one response.
-  #
   # @rbs return: ACP::Transport::Cancellation?
   def cancellation
     ACP::Transport::Cancellation.current
   end
 
+  # @rbs return: Array[untyped]
+  def serving_ids
+    @lock.synchronize { @serving.each_value.map(&:id) }
+  end
+
+  # Joins the requests in flight at the call, not one the reader dispatches
+  # meanwhile: join the reader thread first to leave nothing in flight.
+  #
+  # @rbs return: void
+  def drain
+    @lock.synchronize { @serving.keys }.each(&:join)
+  end
+
   private
 
   # @rbs line: String
@@ -137,8 +148,12 @@ class ACP::Transport::Stdio
     elsif error.is_a?(Hash) && error['code'].is_a?(Integer) && error['message'].is_a?(String)
       code, text, data = error.values_at('code', 'message', 'data')
       settle(message['id'], ACP::RequestError.new(code:, message: text, data:))
-    else
+    elsif message.key?('method')
       reply(detectable_id(message), ACP::RequestError.invalid_request)
+    elsif !settle(message['id'], ACP::RequestError.invalid_response(message))
+      # JSON-RPC responses only answer requests, so a malformed one is never
+      # replied to: the error could settle an unrelated request on the peer.
+      @logger.warn('dropped malformed response: no pending request for its id')
     end
   end
 
@@ -170,39 +185,29 @@ class ACP::Transport::Stdio
   # @rbs method: String
   # @rbs return: void
   def serve(handler, id, params, method)
-    cancellation = register_serving(id)
-    Thread.new do
-      ACP::Transport::Cancellation.current = cancellation
-      outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
-      case outcome
-      when ACP::Transport::Reply
-        reply(id, outcome.result)
-        quietly('reply after callback', &outcome.after)
-      else reply(id, outcome)
+    cancellation = ACP::Transport::Cancellation.new
+    # Registered on the reader thread so a cancel racing the request cannot
+    # be missed. The serve thread starts under the lock so it is registered
+    # before a drain can miss it or it can unregister itself.
+    @lock.synchronize do
+      thread = Thread.new do
+        ACP::Transport::Cancellation.current = cancellation
+        outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
+        case outcome
+        when ACP::Transport::Reply
+          reply(id, outcome.result)
+          quietly('reply after callback', &outcome.after)
+        else reply(id, outcome)
+        end
+      ensure
+        # Unregistered only after the reply and its after callback, so drain waits
+        # for both and later cancels for the id are ignored.
+        @lock.synchronize { @serving.delete(Thread.current) }
       end
-    ensure
-      unregister_serving(id)
+      @serving[thread] = Serving.new(id:, cancellation:)
     end
   end
 
-  # Registered before the serve thread starts so a cancel racing the request
-  # cannot be missed, and dropped once the response is on the wire so later
-  # cancels for the id are ignored.
-  #
-  # @rbs id: untyped
-  # @rbs return: ACP::Transport::Cancellation
-  def register_serving(id)
-    cancellation = ACP::Transport::Cancellation.new
-    @lock.synchronize { @serving[id] = cancellation }
-    cancellation
-  end
-
-  # @rbs id: untyped
-  # @rbs return: void
-  def unregister_serving(id)
-    @lock.synchronize { @serving.delete(id) }
-  end
-
   # A notification has no reply to carry a malformed params failure, so one
   # is warned and dropped rather than answered.
   #
@@ -214,8 +219,10 @@ class ACP::Transport::Stdio
       return @logger.warn('dropped malformed $/cancel_request: missing requestId')
     end
 
-    cancellation = @lock.synchronize { @serving[id] }
-    cancellation&.cancel
+    cancellations = @lock.synchronize do
+      @serving.each_value.filter_map { |entry| entry.cancellation if entry.id == id }
+    end
+    cancellations.each(&:cancel)
   end
 
   # For code with no reply to carry an error: a notification handler, or a
@@ -246,9 +253,6 @@ class ACP::Transport::Stdio
     ACP::RequestError.internal_error
   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 outcome: (_ToH | ACP::RequestError)
   # @rbs return: void
@@ -273,12 +277,15 @@ class ACP::Transport::Stdio
   end
 
   # @rbs id: untyped
-  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
-  # @rbs return: void
+  # @rbs result: untyped
+  # @rbs return: Thread::Queue?
   def settle(id, result)
-    @lock.synchronize { @pending.delete(id) }&.push(result)
+    @lock.synchronize { @pending.delete(id) }&.tap { |queue| queue.push(result) }
   end
 
+  # Leaves @serving alone on purpose: embedders rely on in-flight handlers
+  # running to completion after the input ends.
+  #
   # @rbs return: void
   def close
     @lock.synchronize do
@@ -288,8 +295,9 @@ class ACP::Transport::Stdio
     end
   end
 
-  # A closed peer must not kill the thread writing the reply: the reader has
-  # to keep draining input so pending requests still settle at EOF.
+  # A closed peer (EPIPE) or an output the embedder already closed (IOError)
+  # must not kill the thread writing the reply: the reader has to keep
+  # draining input so pending requests still settle at EOF.
   #
   # @rbs message: Hash[String, untyped]
   # @rbs return: void
@@ -299,7 +307,7 @@ class ACP::Transport::Stdio
       @output.write(line)
       @output.flush
     end
-  rescue Errno::EPIPE => e
+  rescue Errno::EPIPE, IOError => e
     @logger.warn("write to closed peer: #{e.class}: #{e.message}")
   end
 end

data/lib/acp/types/audio_content.rb

@@ -2,50 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::AudioContent
-  # @dynamic annotations
-  attr_reader :annotations #: ACP::Types::Annotations?
+# @rbs!
+#   class ACP::Types::AudioContent = ACP::Types::ContentBlock::Audio
 
-  # @dynamic data
-  attr_reader :data #: String
-
-  # @dynamic mime_type
-  attr_reader :mime_type #: String
-
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs annotations: ACP::Types::Annotations?
-  # @rbs data: String
-  # @rbs mime_type: String
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(data:, mime_type:, annotations: nil, meta: nil)
-    @annotations = annotations
-    @data = data
-    @mime_type = mime_type
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::AudioContent
-  def self.from_h(hash)
-    new(
-      annotations: ACP::Types::Check.object(
-        hash['annotations'],
-        'annotations',
-        ACP::Types::Annotations,
-        allow_nil: true
-      ),
-      data: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'data'), 'data'),
-      mime_type: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'mimeType'), 'mimeType'),
-      meta: hash['_meta']
-    )
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'data' => data, 'mimeType' => mime_type, 'annotations' => annotations&.to_h, '_meta' => meta }.compact
-  end
-end
+ACP::Types::AudioContent = ACP::Types::ContentBlock::Audio

data/lib/acp/types/auth_method_terminal.rb

@@ -2,63 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::AuthMethodTerminal
-  # @dynamic id
-  attr_reader :id #: String
+# @rbs!
+#   class ACP::Types::AuthMethodTerminal = ACP::Types::AuthMethod::Terminal
 
-  # @dynamic name
-  attr_reader :name #: String
-
-  # @dynamic description
-  attr_reader :description #: String?
-
-  # @dynamic args
-  attr_reader :args #: Array[String]?
-
-  # @dynamic env
-  attr_reader :env #: Hash[String, String]?
-
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs id: String
-  # @rbs name: String
-  # @rbs description: String?
-  # @rbs args: Array[String]?
-  # @rbs env: Hash[String, String]?
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(id:, name:, description: nil, args: nil, env: nil, meta: nil)
-    @id = id
-    @name = name
-    @description = description
-    @args = args
-    @env = env
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::AuthMethodTerminal
-  def self.from_h(hash)
-    args = ACP::Types::Check.array(hash['args'], 'args', allow_nil: true) do |item, path|
-      ACP::Types::Check.string(item, path)
-    end
-    env = ACP::Types::Check.hash(hash['env'], 'env', allow_nil: true) do |value, path|
-      ACP::Types::Check.string(value, path)
-    end
-    new(
-      id: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'id'), 'id'),
-      name: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'name'), 'name'),
-      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
-      args:,
-      env:,
-      meta: hash['_meta']
-    )
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'id' => id, 'name' => name, 'description' => description, 'args' => args, 'env' => env, '_meta' => meta }.compact
-  end
-end
+ACP::Types::AuthMethodTerminal = ACP::Types::AuthMethod::Terminal

data/lib/acp/types/available_commands_update.rb

@@ -2,36 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::AvailableCommandsUpdate
-  # @dynamic available_commands
-  attr_reader :available_commands #: Array[ACP::Types::AvailableCommand]
+# @rbs!
+#   class ACP::Types::AvailableCommandsUpdate = ACP::Types::SessionUpdate::AvailableCommandsUpdate
 
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs available_commands: Array[ACP::Types::AvailableCommand]
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(available_commands:, meta: nil)
-    @available_commands = available_commands
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::AvailableCommandsUpdate
-  def self.from_h(hash)
-    available_commands = ACP::Types::Check.array(
-      ACP::Types::Check.key(hash, 'availableCommands'),
-      'availableCommands'
-    ) do |item, path|
-      ACP::Types::Check.object(item, path, ACP::Types::AvailableCommand)
-    end
-    new(available_commands:, meta: hash['_meta'])
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'availableCommands' => available_commands.map(&:to_h), '_meta' => meta }.compact
-  end
-end
+ACP::Types::AvailableCommandsUpdate = ACP::Types::SessionUpdate::AvailableCommandsUpdate

data/lib/acp/types/boolean_property_schema.rb

@@ -2,45 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::BooleanPropertySchema
-  # @dynamic title
-  attr_reader :title #: String?
+# @rbs!
+#   class ACP::Types::BooleanPropertySchema = ACP::Types::ElicitationPropertySchema::BooleanPropertySchema
 
-  # @dynamic description
-  attr_reader :description #: String?
-
-  # @dynamic default
-  attr_reader :default #: bool?
-
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs title: String?
-  # @rbs description: String?
-  # @rbs default: bool?
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(title: nil, description: nil, default: nil, meta: nil)
-    @title = title
-    @description = description
-    @default = default
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::BooleanPropertySchema
-  def self.from_h(hash)
-    new(
-      title: ACP::Types::Check.string(hash['title'], 'title', allow_nil: true),
-      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
-      default: ACP::Types::Check.boolean(hash['default'], 'default', allow_nil: true),
-      meta: hash['_meta']
-    )
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'title' => title, 'description' => description, 'default' => default, '_meta' => meta }.compact
-  end
-end
+ACP::Types::BooleanPropertySchema = ACP::Types::ElicitationPropertySchema::BooleanPropertySchema