acp-sdk 0.1.0

data/lib/acp/transport/stdio.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+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.
+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 @next_id: Integer
+  # @rbs @closed: bool
+
+  INTERNAL_ERROR = -32_603 #: Integer
+  PARSE_ERROR = ACP::Transport::ResponseError.new(code: -32_700, message: 'Parse error') #: ACP::Transport::ResponseError
+  INVALID_REQUEST = ACP::Transport::ResponseError.new(code: -32_600, message: 'Invalid request') #: ACP::Transport::ResponseError
+  METHOD_NOT_FOUND = ACP::Transport::ResponseError.new(code: -32_601, message: 'Method not found') #: ACP::Transport::ResponseError
+  CONNECTION_CLOSED = ACP::Transport::ResponseError.new(code: INTERNAL_ERROR, message: 'Connection closed') #: ACP::Transport::ResponseError
+
+  # @rbs input: _Reader
+  # @rbs output: _Writer
+  # @rbs return: void
+  def initialize(input:, output:)
+    @input = input
+    @output = output
+    @write_lock = Mutex.new
+    @lock = Mutex.new
+    @pending = {}
+    @next_id = 0
+    @closed = false
+  end
+
+  # Returns the reader thread, which ends at EOF on input after releasing any
+  # pending outbound requests.
+  #
+  # @rbs requests: Hash[String, _Handler]
+  # @rbs notifications: Hash[String, _NotificationHandler]
+  # @rbs return: Thread
+  def start(requests: {}, notifications: {})
+    Thread.new do
+      # Binary copy: String#strip raises on invalid UTF-8, which parse reports.
+      @input.each_line { |line| receive(line, requests, notifications) unless line.b.strip.empty? }
+    ensure
+      close
+    end
+  end
+
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: ACP::Transport::Result
+  def request(method, params = nil)
+    queue = Thread::Queue.new
+    id = register(queue)
+    return ACP::Transport::Result.error(CONNECTION_CLOSED) unless id
+
+    write({ 'jsonrpc' => '2.0', 'id' => id, 'method' => method, 'params' => params }.compact)
+    queue.pop || ACP::Transport::Result.error(CONNECTION_CLOSED)
+  end
+
+  # @rbs method: String
+  # @rbs params: untyped
+  # @rbs return: void
+  def notify(method, params = nil)
+    write({ 'jsonrpc' => '2.0', 'method' => method, 'params' => params }.compact)
+  end
+
+  private
+
+  # @rbs line: String
+  # @rbs requests: Hash[String, _Handler]
+  # @rbs notifications: Hash[String, _NotificationHandler]
+  # @rbs return: void
+  def receive(line, requests, notifications)
+    message = parse(line)
+    case message
+    when ACP::Transport::ResponseError then reply(nil, ACP::Transport::Result.error(message))
+    else route(message, requests, notifications)
+    end
+  end
+
+  # @rbs message: Hash[String, untyped]
+  # @rbs requests: Hash[String, _Handler]
+  # @rbs notifications: Hash[String, _NotificationHandler]
+  # @rbs return: void
+  def route(message, requests, notifications)
+    method = message['method']
+    error = message['error']
+    if method.is_a?(String) && message.key?('id')
+      serve(requests[method], message['id'], message['params'])
+    elsif method.is_a?(String)
+      # Run on the reader thread so notifications (session/update) keep their
+      # order; a JSON-RPC notification has no reply to carry a handler error.
+      handler = notifications[method]
+      quietly { handler.call(message['params']) } if handler
+    elsif message.key?('result')
+      settle(message['id'], ACP::Transport::Result.ok(message['result']))
+    elsif error.is_a?(Hash) && error['code'].is_a?(Integer) && error['message'].is_a?(String)
+      code, text, data = error.values_at('code', 'message', 'data')
+      response_error = ACP::Transport::ResponseError.new(code:, message: text, data:)
+      settle(message['id'], ACP::Transport::Result.error(response_error))
+    else
+      reply(nil, ACP::Transport::Result.error(INVALID_REQUEST))
+    end
+  end
+
+  # @rbs line: String
+  # @rbs return: Hash[String, untyped] | ACP::Transport::ResponseError
+  def parse(line)
+    return PARSE_ERROR unless line.valid_encoding?
+
+    message = JSON.parse(line)
+    message.is_a?(Hash) ? message : INVALID_REQUEST
+  rescue JSON::ParserError
+    PARSE_ERROR
+  end
+
+  # @rbs handler: _Handler?
+  # @rbs id: untyped
+  # @rbs params: untyped
+  # @rbs return: void
+  def serve(handler, id, params)
+    Thread.new do
+      outcome = handler ? invoke(handler, params) : ACP::Transport::Result.error(METHOD_NOT_FOUND)
+      case outcome
+      when ACP::Transport::Reply
+        reply(id, outcome.result)
+        quietly(&outcome.after)
+      else reply(id, outcome)
+      end
+    end
+  end
+
+  # For code with no reply to carry an error: a notification handler, or a
+  # Reply's after once the reply is on the wire. An exception must not kill
+  # the reader thread or print a thread report.
+  #
+  # @rbs &block: () -> void
+  # @rbs return: void
+  def quietly
+    yield
+  rescue StandardError
+    nil
+  end
+
+  # Handlers are application code at the protocol boundary: an exception
+  # becomes an error response instead of killing the thread serving it.
+  #
+  # @rbs handler: _Handler
+  # @rbs params: untyped
+  # @rbs return: ACP::Transport::Result | ACP::Transport::Reply
+  def invoke(handler, params)
+    handler.call(params)
+  rescue StandardError => e
+    ACP::Transport::Result.error(ACP::Transport::ResponseError.new(code: INTERNAL_ERROR, message: e.message))
+  end
+
+  # @rbs id: untyped
+  # @rbs result: ACP::Transport::Result
+  # @rbs return: void
+  def reply(id, result)
+    error = result.error
+    write({ 'jsonrpc' => '2.0', 'id' => id }.merge(error ? { 'error' => error.to_h } : { 'result' => result.value }))
+  end
+
+  # @rbs queue: Thread::Queue
+  # @rbs return: Integer?
+  def register(queue)
+    @lock.synchronize do
+      next if @closed
+
+      id = @next_id += 1
+      @pending[id] = queue
+      id
+    end
+  end
+
+  # @rbs id: untyped
+  # @rbs result: ACP::Transport::Result
+  # @rbs return: void
+  def settle(id, result)
+    @lock.synchronize { @pending.delete(id) }&.push(result)
+  end
+
+  # @rbs return: void
+  def close
+    @lock.synchronize do
+      @closed = true
+      @pending.each_value(&:close)
+      @pending.clear
+    end
+  end
+
+  # @rbs message: Hash[String, untyped]
+  # @rbs return: void
+  def write(message)
+    line = "#{JSON.generate(message)}\n"
+    @write_lock.synchronize do
+      @output.write(line)
+      @output.flush
+    end
+  end
+end

data/lib/acp/transport.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module ACP::Transport
+end

data/lib/acp/types/agent_auth_capabilities.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AgentAuthCapabilities
+  # @dynamic logout
+  attr_reader :logout #: ACP::Types::LogoutCapabilities?
+
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs logout: ACP::Types::LogoutCapabilities?
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(logout: nil, meta: nil)
+    @logout = logout
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::AgentAuthCapabilities
+  def self.from_h(hash)
+    new(logout: hash['logout']&.then { |value| ACP::Types::LogoutCapabilities.from_h(value) }, meta: hash['_meta'])
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'logout' => logout&.to_h, '_meta' => meta }.compact
+  end
+end

data/lib/acp/types/agent_capabilities.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AgentCapabilities
+  # @dynamic load_session
+  attr_reader :load_session #: bool?
+
+  # @dynamic prompt_capabilities
+  attr_reader :prompt_capabilities #: ACP::Types::PromptCapabilities?
+
+  # @dynamic mcp_capabilities
+  attr_reader :mcp_capabilities #: ACP::Types::McpCapabilities?
+
+  # @dynamic session_capabilities
+  attr_reader :session_capabilities #: ACP::Types::SessionCapabilities?
+
+  # @dynamic auth
+  attr_reader :auth #: ACP::Types::AgentAuthCapabilities?
+
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs load_session: bool?
+  # @rbs prompt_capabilities: ACP::Types::PromptCapabilities?
+  # @rbs mcp_capabilities: ACP::Types::McpCapabilities?
+  # @rbs session_capabilities: ACP::Types::SessionCapabilities?
+  # @rbs auth: ACP::Types::AgentAuthCapabilities?
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(
+    load_session: nil,
+    prompt_capabilities: nil,
+    mcp_capabilities: nil,
+    session_capabilities: nil,
+    auth: nil,
+    meta: nil
+  )
+    @load_session = load_session
+    @prompt_capabilities = prompt_capabilities
+    @mcp_capabilities = mcp_capabilities
+    @session_capabilities = session_capabilities
+    @auth = auth
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::AgentCapabilities
+  def self.from_h(hash)
+    new(
+      load_session: hash['loadSession'],
+      prompt_capabilities: hash['promptCapabilities']&.then { |value| ACP::Types::PromptCapabilities.from_h(value) },
+      mcp_capabilities: hash['mcpCapabilities']&.then { |value| ACP::Types::McpCapabilities.from_h(value) },
+      session_capabilities: hash['sessionCapabilities']&.then { |value| ACP::Types::SessionCapabilities.from_h(value) },
+      auth: hash['auth']&.then { |value| ACP::Types::AgentAuthCapabilities.from_h(value) },
+      meta: hash['_meta']
+    )
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    {
+      'loadSession' => load_session,
+      'promptCapabilities' => prompt_capabilities&.to_h,
+      'mcpCapabilities' => mcp_capabilities&.to_h,
+      'sessionCapabilities' => session_capabilities&.to_h,
+      'auth' => auth&.to_h,
+      '_meta' => meta
+    }.compact
+  end
+end

data/lib/acp/types/annotations.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::Annotations
+  # @dynamic audience
+  attr_reader :audience #: Array[String]?
+
+  # @dynamic last_modified
+  attr_reader :last_modified #: String?
+
+  # @dynamic priority
+  attr_reader :priority #: Numeric?
+
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs audience: Array[String]?
+  # @rbs last_modified: String?
+  # @rbs priority: Numeric?
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(audience: nil, last_modified: nil, priority: nil, meta: nil)
+    @audience = audience
+    @last_modified = last_modified
+    @priority = priority
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::Annotations
+  def self.from_h(hash)
+    new(
+      audience: hash['audience'],
+      last_modified: hash['lastModified'],
+      priority: hash['priority'],
+      meta: hash['_meta']
+    )
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'audience' => audience, 'lastModified' => last_modified, 'priority' => priority, '_meta' => meta }.compact
+  end
+end

data/lib/acp/types/audio_content.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AudioContent
+  # @dynamic annotations
+  attr_reader :annotations #: ACP::Types::Annotations?
+
+  # @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: hash['annotations']&.then { |value| ACP::Types::Annotations.from_h(value) },
+      data: hash.fetch('data'),
+      mime_type: hash.fetch('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

data/lib/acp/types/auth_capabilities.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AuthCapabilities
+  # @dynamic terminal
+  attr_reader :terminal #: bool?
+
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs terminal: bool?
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(terminal: nil, meta: nil)
+    @terminal = terminal
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::AuthCapabilities
+  def self.from_h(hash)
+    new(terminal: hash['terminal'], meta: hash['_meta'])
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'terminal' => terminal, '_meta' => meta }.compact
+  end
+end

data/lib/acp/types/auth_method/terminal.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AuthMethod::Terminal
+  # @dynamic id
+  attr_reader :id #: String
+
+  # @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::AuthMethod::Terminal
+  def self.from_h(hash)
+    new(
+      id: hash.fetch('id'),
+      name: hash.fetch('name'),
+      description: hash['description'],
+      args: hash['args'],
+      env: hash['env'],
+      meta: hash['_meta']
+    )
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    {
+      'type' => 'terminal',
+      'id' => id,
+      'name' => name,
+      'description' => description,
+      'args' => args,
+      'env' => env,
+      '_meta' => meta
+    }.compact
+  end
+end

data/lib/acp/types/auth_method.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+module ACP::Types::AuthMethod
+  # @rbs!
+  #   type t = ACP::Types::AuthMethod::Terminal
+  #          | ACP::Types::AuthMethodAgent
+  #          | Hash[String, untyped]
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: t
+  def self.from_h(hash)
+    case hash['type']
+    when 'terminal' then ACP::Types::AuthMethod::Terminal.from_h(hash)
+    when nil then ACP::Types::AuthMethodAgent.from_h(hash)
+    else hash
+    end
+  end
+end

data/lib/acp/types/auth_method_agent.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AuthMethodAgent
+  # @dynamic id
+  attr_reader :id #: String
+
+  # @dynamic name
+  attr_reader :name #: String
+
+  # @dynamic description
+  attr_reader :description #: String?
+
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs id: String
+  # @rbs name: String
+  # @rbs description: String?
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(id:, name:, description: nil, meta: nil)
+    @id = id
+    @name = name
+    @description = description
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::AuthMethodAgent
+  def self.from_h(hash)
+    new(id: hash.fetch('id'), name: hash.fetch('name'), description: hash['description'], meta: hash['_meta'])
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'id' => id, 'name' => name, 'description' => description, '_meta' => meta }.compact
+  end
+end

data/lib/acp/types/auth_method_terminal.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AuthMethodTerminal
+  # @dynamic id
+  attr_reader :id #: String
+
+  # @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)
+    new(
+      id: hash.fetch('id'),
+      name: hash.fetch('name'),
+      description: hash['description'],
+      args: hash['args'],
+      env: hash['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

data/lib/acp/types/authenticate_request.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AuthenticateRequest
+  # @dynamic method_id
+  attr_reader :method_id #: String
+
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs method_id: String
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(method_id:, meta: nil)
+    @method_id = method_id
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::AuthenticateRequest
+  def self.from_h(hash)
+    new(method_id: hash.fetch('methodId'), meta: hash['_meta'])
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { 'methodId' => method_id, '_meta' => meta }.compact
+  end
+end

data/lib/acp/types/authenticate_response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Generated by bin/types from schema/schema.json. Do not edit.
+
+class ACP::Types::AuthenticateResponse
+  # @dynamic meta
+  attr_reader :meta #: Hash[String, untyped]?
+
+  # @rbs meta: Hash[String, untyped]?
+  # @rbs return: void
+  def initialize(meta: nil)
+    @meta = meta
+    freeze
+  end
+
+  # @rbs hash: Hash[String, untyped]
+  # @rbs return: ACP::Types::AuthenticateResponse
+  def self.from_h(hash)
+    new(meta: hash['_meta'])
+  end
+
+  # @rbs return: Hash[String, untyped]
+  def to_h
+    { '_meta' => meta }.compact
+  end
+end