arcp 1.0.0

data/lib/arcp/client.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/queue'
+require 'time'
+
+require_relative 'envelope'
+require_relative 'errors'
+require_relative 'message_types'
+require_relative 'session'
+require_relative 'job'
+require_relative 'lease'
+require_relative 'trace'
+require_relative 'ids'
+require_relative 'clock'
+
+module Arcp
+  # ARCP client: opens a session over a transport, submits jobs,
+  # consumes events, and provides cursored job listings.
+  #
+  # @example Connect over an in-memory transport pair
+  #   server_t, client_t = Arcp::Transport::MemoryTransport.pair
+  #   Sync do
+  #     client = Arcp::Client.open(
+  #       transport: client_t,
+  #       auth: { 'scheme' => 'bearer', 'token' => 'demo' }
+  #     )
+  #     handle = client.submit_job(agent: 'echo', input: { 'msg' => 'hi' })
+  #     handle.subscribe(client: client).each { |ev| puts ev.kind }
+  #     client.close
+  #   end
+  class Client
+    attr_reader :session, :transport
+
+    def self.open(transport:, auth:, client_name: 'arcp-ruby', client_version: Arcp::VERSION,
+                  capabilities: nil, resume: nil, clock: Arcp::SystemClock.new)
+      client = new(transport: transport, clock: clock)
+      client.handshake!(auth: auth, client_name: client_name, client_version: client_version,
+                        capabilities: capabilities, resume: resume)
+      client
+    end
+
+    def initialize(transport:, clock: Arcp::SystemClock.new)
+      @transport = transport
+      @clock = clock
+      @session = nil
+      @inbox = Async::Queue.new
+      @pending = {}
+      @job_streams = {}
+      @job_results = {}
+      @result_waiters = {}
+      @reader_task = nil
+      @heartbeat_task = nil
+      @next_outbound_seq = 0
+      @inbound_seq = 0
+      @closed = false
+      @mutex = Mutex.new
+    end
+
+    def handshake!(auth:, client_name:, client_version:, capabilities: nil, resume: nil)
+      caps = capabilities || Arcp::Session::CapabilitySet.local
+      session_id = Arcp::Ids.session_id
+      hello = Arcp::Session::Hello.new(
+        client_name: client_name, client_version: client_version,
+        auth: auth, capabilities: caps, resume: resume
+      )
+      env = Arcp::Envelope.build(
+        type: Arcp::MessageTypes::SESSION_HELLO,
+        session_id: session_id,
+        payload: hello.to_h
+      )
+      @transport.send(env)
+
+      welcome_env = @transport.receive
+      raise Arcp::Errors::ProtocolViolation, 'transport closed before welcome' if welcome_env.nil?
+
+      case welcome_env.type
+      when Arcp::MessageTypes::SESSION_WELCOME
+        welcome = Arcp::Session::Welcome.from_h(welcome_env.payload)
+        effective = caps.intersect(welcome.capabilities)
+        @session = Arcp::Session::Info.new(
+          id: welcome_env.session_id,
+          runtime_version: welcome.runtime_version,
+          capabilities: effective,
+          agents: welcome.capabilities.agents,
+          heartbeat_interval_sec: welcome.heartbeat_interval_sec,
+          resume_token: welcome.resume_token,
+          resume_window_sec: welcome.resume_window_sec
+        )
+      when Arcp::MessageTypes::SESSION_ERROR
+        err = Arcp::Session::SessionError.from_h(welcome_env.payload)
+        raise Arcp::Errors.for(err.code, message: err.message, details: err.details || {})
+      else
+        raise Arcp::Errors::ProtocolViolation, "expected session.welcome, got #{welcome_env.type}"
+      end
+
+      start_reader!
+      if @session.supports?(Arcp::Session::Feature::HEARTBEAT) && @session.heartbeat_interval_sec
+        start_heartbeat!
+      end
+      @session
+    end
+
+    def list_jobs(status: nil, agent: nil, created_after: nil, limit: nil, cursor: nil)
+      require_feature!(Arcp::Session::Feature::LIST_JOBS)
+
+      Enumerator.new do |yielder|
+        next_cursor = cursor
+        loop do
+          payload = Arcp::Session::ListJobs.new(
+            filter: { 'status' => status, 'agent' => agent, 'created_after' => created_after }.compact,
+            limit: limit,
+            cursor: next_cursor
+          ).to_h
+          response = request(type: Arcp::MessageTypes::SESSION_LIST_JOBS,
+                             expect: Arcp::MessageTypes::SESSION_JOBS,
+                             payload: payload)
+          jobs = Arcp::Session::JobsResponse.from_h(response.payload)
+          jobs.jobs.each { |j| yielder << Arcp::Job::Summary.from_h(j) }
+          next_cursor = jobs.next_cursor
+          break if next_cursor.nil?
+        end
+      end.lazy
+    end
+
+    def submit_job(agent:, input: nil, lease_request: nil, lease_constraints: nil,
+                   idempotency_key: nil, max_runtime_sec: nil)
+      lease_constraints&.validate!
+
+      submit = Arcp::Job::Submit.new(
+        agent: agent, input: input,
+        lease_request: lease_request, lease_constraints: lease_constraints,
+        idempotency_key: idempotency_key, max_runtime_sec: max_runtime_sec
+      )
+      accepted_env = request(
+        type: Arcp::MessageTypes::JOB_SUBMIT,
+        expect: Arcp::MessageTypes::JOB_ACCEPTED,
+        payload: submit.to_h
+      )
+      accepted = Arcp::Job::Accepted.from_h(accepted_env.payload)
+      Arcp::Job::Handle.new(
+        job_id: accepted.job_id, agent: accepted.agent,
+        submitted_at: accepted.accepted_at,
+        lease: accepted.lease,
+        credentials: accepted.credentials
+      )
+    end
+
+    def subscribe_job(job_id:, from_event_seq: nil, history: false)
+      queue = @mutex.synchronize { @job_streams[job_id] ||= Async::Queue.new }
+
+      if @session.supports?(Arcp::Session::Feature::SUBSCRIBE) && from_event_seq
+        send_envelope(type: Arcp::MessageTypes::JOB_SUBSCRIBE,
+                      job_id: job_id,
+                      payload: Arcp::Job::Subscribe.new(job_id: job_id, from_event_seq: from_event_seq,
+                                                        history: history).to_h)
+      end
+
+      Enumerator.new do |yielder|
+        loop do
+          item = queue.dequeue
+          break if item.nil? || item == :__arcp_end__
+
+          yielder << item
+        end
+      end
+    end
+
+    def cancel_job(job_id:, reason: nil)
+      send_envelope(type: Arcp::MessageTypes::JOB_CANCEL,
+                    job_id: job_id,
+                    payload: Arcp::Job::Cancel.new(job_id: job_id, reason: reason).to_h)
+    end
+
+    def get_result(job_id:)
+      env = @mutex.synchronize { @job_results[job_id] }
+      if env.nil?
+        queue = Async::Queue.new
+        @mutex.synchronize { @result_waiters[job_id] = queue }
+        env = queue.dequeue
+      end
+      case env.type
+      when Arcp::MessageTypes::JOB_RESULT
+        Arcp::Job::Result.from_h(env.payload)
+      when Arcp::MessageTypes::JOB_ERROR
+        raise Arcp::Job::JobError.from_h(env.payload).to_exception
+      else
+        raise Arcp::Errors::ProtocolViolation, "unexpected #{env.type}"
+      end
+    end
+
+    def ack(seq)
+      require_feature!(Arcp::Session::Feature::ACK)
+      send_envelope(type: Arcp::MessageTypes::SESSION_ACK,
+                    payload: Arcp::Session::Ack.new(last_processed_seq: seq).to_h)
+    end
+
+    def send_envelope(type:, payload:, job_id: nil)
+      raise Arcp::Errors::Internal, 'session not open' unless @session
+      raise IOError, 'client closed' if @closed
+
+      env = Arcp::Envelope.build(
+        type: type, session_id: @session.id,
+        trace_id: Arcp::Trace.current.trace_id,
+        job_id: job_id, payload: payload
+      )
+      @transport.send(env)
+      env
+    end
+
+    def close(reason: nil)
+      return if @closed
+
+      @closed = true
+      begin
+        send_envelope(type: Arcp::MessageTypes::SESSION_BYE,
+                      payload: Arcp::Session::Bye.new(reason: reason).to_h)
+      rescue StandardError
+        nil
+      end
+      @heartbeat_task&.stop
+      @reader_task&.stop
+      @transport.close(reason: reason)
+      drain_streams
+      nil
+    end
+
+    private
+
+    def require_feature!(feature)
+      return if @session.supports?(feature)
+
+      raise Arcp::Errors::UnnegotiatedFeature, "feature not negotiated: #{feature}"
+    end
+
+    def request(type:, expect:, payload:)
+      env = send_envelope(type: type, payload: payload)
+      queue = Async::Queue.new
+      @mutex.synchronize { @pending[env.id] = [expect, queue] }
+      response = queue.dequeue
+      raise Arcp::Errors::ProtocolViolation, 'transport closed' if response.nil?
+
+      case response.type
+      when expect
+        response
+      when Arcp::MessageTypes::JOB_ERROR
+        raise Arcp::Job::JobError.from_h(response.payload).to_exception
+      when Arcp::MessageTypes::SESSION_ERROR
+        err = Arcp::Session::SessionError.from_h(response.payload)
+        raise Arcp::Errors.for(err.code, message: err.message, details: err.details || {})
+      else
+        raise Arcp::Errors::ProtocolViolation, "expected #{expect}, got #{response.type}"
+      end
+    end
+
+    def start_reader!
+      @reader_task = Async do |_task|
+        loop do
+          env = @transport.receive
+          break if env.nil?
+
+          dispatch(env)
+        end
+      rescue Async::Stop
+        nil
+      ensure
+        drain_streams
+      end
+    end
+
+    def start_heartbeat!
+      interval = @session.heartbeat_interval_sec
+      @heartbeat_task = Async do |task|
+        loop do
+          task.sleep(interval)
+          next if @closed
+
+          send_envelope(
+            type: Arcp::MessageTypes::SESSION_PING,
+            payload: Arcp::Session::Ping.new(nonce: Arcp::Ids.envelope_id, sent_at: @clock.now.iso8601).to_h
+          )
+        rescue StandardError
+          nil
+        end
+      rescue Async::Stop
+        nil
+      end
+    end
+
+    def dispatch(env)
+      @inbound_seq = env.event_seq if env.event_seq
+
+      case env.type
+      when Arcp::MessageTypes::JOB_EVENT
+        feed_job_stream(env)
+      when Arcp::MessageTypes::JOB_RESULT, Arcp::MessageTypes::JOB_ERROR
+        feed_pending(env) # may satisfy a pending submit/get_result waiter
+        feed_result(env)
+        feed_job_stream(env, end_stream: true)
+      when Arcp::MessageTypes::SESSION_PING
+        ping = Arcp::Session::Ping.from_h(env.payload)
+        send_envelope(type: Arcp::MessageTypes::SESSION_PONG,
+                      payload: Arcp::Session::Pong.new(ping_nonce: ping.nonce,
+                                                       received_at: @clock.now.iso8601).to_h)
+      when Arcp::MessageTypes::SESSION_PONG
+        # noop — receipt of any inbound resets timer (implicit)
+      else
+        feed_pending(env)
+      end
+    end
+
+    def feed_job_stream(env, end_stream: false)
+      queue = @mutex.synchronize { @job_streams[env.job_id] ||= Async::Queue.new }
+
+      queue.enqueue(Arcp::Job::Event.from_h(env.payload)) if env.type == Arcp::MessageTypes::JOB_EVENT
+
+      queue.enqueue(:__arcp_end__) if end_stream
+    end
+
+    def feed_result(env)
+      waiter = @mutex.synchronize do
+        @job_results[env.job_id] = env
+        @result_waiters.delete(env.job_id)
+      end
+      waiter&.enqueue(env)
+    end
+
+    def feed_pending(env)
+      reply_to = env.payload.is_a?(Hash) ? env.payload['reply_to'] : nil
+      key = reply_to || @mutex.synchronize do
+        @pending.keys.find do |k|
+          @pending[k].is_a?(Array) && @pending[k][0] == env.type
+        end
+      end
+      return unless key
+
+      pair = @mutex.synchronize { @pending.delete(key) }
+      pair&.last&.enqueue(env)
+    end
+
+    def drain_streams
+      @mutex.synchronize do
+        @job_streams.each_value { |q| q.enqueue(:__arcp_end__) }
+        @job_streams.clear
+        @pending.each_value do |v|
+          (v.is_a?(Array) ? v[1] : v).enqueue(nil)
+        end
+        @pending.clear
+        @result_waiters.each_value { |q| q.enqueue(nil) }
+        @result_waiters.clear
+      end
+    end
+  end
+end

data/lib/arcp/clock.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Arcp
+  module Clock
+    module_function
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    def now = Time.now.utc
+  end
+
+  class SystemClock
+    def now = Time.now.utc
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  class FakeClock
+    attr_accessor :now_value, :monotonic_value
+
+    def initialize(now: Time.utc(2026, 1, 1))
+      @now_value = now.utc
+      @monotonic_value = 0.0
+    end
+
+    def now = @now_value
+    def monotonic = @monotonic_value
+
+    def advance(seconds)
+      @now_value += seconds
+      @monotonic_value += seconds
+      self
+    end
+  end
+end

data/lib/arcp/credential.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Arcp
+  Credential = Data.define(:id, :scheme, :value, :endpoint, :profile, :constraints) do
+    def initialize(id:, scheme:, value:, endpoint:, profile: nil, constraints: nil)
+      super(
+        id: id,
+        scheme: scheme,
+        value: value,
+        endpoint: endpoint,
+        profile: profile,
+        constraints: constraints || {}
+      )
+    end
+
+    def self.from_h(h)
+      h = h.transform_keys(&:to_s)
+      new(
+        id: h.fetch('id'),
+        scheme: h.fetch('scheme'),
+        value: h.fetch('value'),
+        endpoint: h.fetch('endpoint'),
+        profile: h['profile'],
+        constraints: h['constraints'] || {}
+      )
+    end
+
+    def to_h
+      out = { 'id' => id, 'scheme' => scheme, 'value' => value, 'endpoint' => endpoint }
+      out['profile'] = profile if profile
+      out['constraints'] = constraints if constraints && !constraints.empty?
+      out
+    end
+
+    def to_redacted_h
+      to_h.merge('value' => '[REDACTED]')
+    end
+  end
+
+  Credential.const_set(:SCHEME_BEARER, 'bearer') unless Credential.const_defined?(:SCHEME_BEARER)
+
+  module ModelPattern
+    FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    module_function
+
+    def match?(patterns, model_id)
+      Array(patterns).any? { |pattern| File.fnmatch?(pattern, model_id, FLAGS) }
+    end
+
+    def implied_by?(parent_patterns, child_pattern)
+      Array(parent_patterns).any? do |parent|
+        child_pattern == parent || literal_match?(parent, child_pattern)
+      end
+    end
+
+    def literal_match?(parent_pattern, child_pattern)
+      !glob?(child_pattern) && match?([parent_pattern], child_pattern)
+    end
+
+    def glob?(pattern)
+      pattern.match?(/[*?\[\]{}]/)
+    end
+  end
+end

data/lib/arcp/credential_provisioner.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'credential'
+require_relative 'errors'
+
+module Arcp
+  module CredentialProvisioner
+    def issue(lease:, job_id:, agent:, principal_id:)
+      raise NotImplementedError
+    end
+
+    def revoke(credential_id:)
+      raise NotImplementedError
+    end
+  end
+
+  module Credentials
+    BUDGET_EXHAUSTED_CODES = %w[BUDGET_EXHAUSTED budget_exhausted insufficient_quota].freeze
+
+    def self.translate_upstream_error(error)
+      return error unless budget_exhausted?(error)
+
+      Arcp::Errors::BudgetExhausted.new(
+        error.message,
+        details: { 'upstream_class' => error.class.name }
+      )
+    end
+
+    def self.budget_exhausted?(error)
+      code = error.respond_to?(:code) ? error.code.to_s : nil
+      status = error.respond_to?(:status) ? error.status.to_i : nil
+      BUDGET_EXHAUSTED_CODES.include?(code) || status == 402
+    end
+
+    class InMemoryProvisioner
+      include Arcp::CredentialProvisioner
+
+      attr_reader :issued, :revoked
+
+      def initialize(endpoint: 'https://gateway.test/v1', profile: 'openai')
+        @endpoint = endpoint
+        @profile = profile
+        @issued = []
+        @revoked = []
+      end
+
+      def issue(lease:, job_id:, agent:, principal_id:)
+        credential = Arcp::Credential.new(
+          id: "cred_#{job_id}_0",
+          scheme: Arcp::Credential::SCHEME_BEARER,
+          value: "sk-test-#{job_id}",
+          endpoint: @endpoint,
+          profile: @profile,
+          constraints: constraints_for(lease)
+        )
+        @issued << {
+          credential: credential,
+          job_id: job_id,
+          agent: agent,
+          principal_id: principal_id
+        }
+        [credential]
+      end
+
+      def revoke(credential_id:)
+        @revoked << credential_id
+        nil
+      end
+
+      private
+
+      def constraints_for(lease)
+        return {} unless lease
+
+        {
+          'cost.budget' => lease.budget&.to_a,
+          'model.use' => lease.model_use,
+          'expires_at' => lease.expires_at
+        }.compact
+      end
+    end
+
+    class CredentialStore
+      def record(job_id:, credential_id:)
+        raise NotImplementedError
+      end
+
+      def forget(job_id:, credential_id:)
+        raise NotImplementedError
+      end
+
+      def outstanding(job_id:)
+        raise NotImplementedError
+      end
+
+      def all_outstanding
+        raise NotImplementedError
+      end
+    end
+
+    class InMemoryStore < CredentialStore
+      def initialize
+        super
+        @by_job = Hash.new { |hash, key| hash[key] = [] }
+        @mutex = Mutex.new
+      end
+
+      def record(job_id:, credential_id:)
+        @mutex.synchronize { @by_job[job_id] |= [credential_id] }
+        nil
+      end
+
+      def forget(job_id:, credential_id:)
+        @mutex.synchronize do
+          @by_job[job_id].delete(credential_id)
+          @by_job.delete(job_id) if @by_job[job_id].empty?
+        end
+        nil
+      end
+
+      def outstanding(job_id:)
+        @mutex.synchronize { @by_job[job_id].dup.freeze }
+      end
+
+      def all_outstanding
+        @mutex.synchronize do
+          @by_job.transform_values { |ids| ids.dup.freeze }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/arcp/envelope.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'ids'
+require_relative 'errors'
+require_relative 'serializer'
+require_relative 'message_types'
+
+module Arcp
+  # ARCP wire envelope per spec §5.1. Eight fields:
+  # arcp, id, type, session_id, trace_id, job_id, event_seq, payload.
+  #
+  # `trace_id` and `job_id` may be nil for session-level envelopes.
+  # `event_seq` is nil for non-event traffic; events carry a monotonic Integer.
+  Envelope = Data.define(:arcp, :id, :type, :session_id, :trace_id, :job_id, :event_seq, :payload) do
+    HEX32 = /\A[0-9a-f]{32}\z/
+
+    def self.build(type:, session_id:, payload:, trace_id: nil, job_id: nil, event_seq: nil, id: nil)
+      raise Arcp::Errors::InvalidRequest, 'trace_id must be 32 hex chars' if trace_id && trace_id !~ HEX32
+
+      new(
+        arcp: Arcp::PROTOCOL_VERSION,
+        id: id || Arcp::Ids.envelope_id,
+        type: type,
+        session_id: session_id,
+        trace_id: trace_id,
+        job_id: job_id,
+        event_seq: event_seq,
+        payload: payload || {}
+      )
+    end
+
+    def self.from_h(hash)
+      raise Arcp::Errors::InvalidRequest, 'envelope must be a Hash' unless hash.is_a?(Hash)
+
+      h = hash.transform_keys(&:to_s)
+      arcp = h['arcp']
+      unless arcp == Arcp::PROTOCOL_VERSION
+        raise Arcp::Errors::InvalidRequest, "unsupported arcp version: #{arcp.inspect}"
+      end
+
+      type = h['type']
+      raise Arcp::Errors::InvalidRequest, 'envelope type must be a String' unless type.is_a?(String)
+
+      session_id = h['session_id']
+      unless session_id.is_a?(String)
+        raise Arcp::Errors::InvalidRequest,
+              'envelope session_id must be a String'
+      end
+
+      event_seq = h['event_seq']
+      unless event_seq.nil? || event_seq.is_a?(Integer)
+        raise Arcp::Errors::InvalidRequest,
+              'event_seq must be an Integer'
+      end
+
+      trace_id = h['trace_id']
+      raise Arcp::Errors::InvalidRequest, 'trace_id must be 32 hex chars' if trace_id && trace_id !~ HEX32
+
+      payload = h['payload']
+      raise Arcp::Errors::InvalidRequest, 'payload must be a Hash' unless payload.is_a?(Hash) || payload.nil?
+
+      new(
+        arcp: arcp,
+        id: h.fetch('id'),
+        type: type,
+        session_id: session_id,
+        trace_id: trace_id,
+        job_id: h['job_id'],
+        event_seq: event_seq,
+        payload: deep_freeze(payload || {})
+      )
+    end
+
+    def self.from_json(bytes)
+      from_h(Arcp::Serializer.load(bytes))
+    end
+
+    def self.deep_freeze(value)
+      case value
+      when Hash
+        value.each_value { |v| deep_freeze(v) }
+      when Array
+        value.each { |v| deep_freeze(v) }
+      end
+      value.freeze
+    end
+
+    def to_h
+      h = { 'arcp' => arcp, 'id' => id, 'type' => type, 'session_id' => session_id,
+            'payload' => stringify(payload) }
+      h['trace_id']  = trace_id  if trace_id
+      h['job_id']    = job_id    if job_id
+      h['event_seq'] = event_seq if event_seq
+      h
+    end
+
+    def to_json(*_args) = Arcp::Serializer.dump(to_h)
+
+    def stringify(value)
+      case value
+      when Hash  then value.transform_keys(&:to_s).transform_values { |v| stringify(v) }
+      when Array then value.map { |v| stringify(v) }
+      else value
+      end
+    end
+
+    def known? = Arcp::MessageTypes.known?(type)
+  end
+
+  UnknownEnvelope = Data.define(:envelope) do
+    def type = envelope.type
+    def payload = envelope.payload
+  end
+end