arcp 1.0.0

data/lib/arcp/runtime/session_actor.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/queue'
+require 'time'
+
+module Arcp
+  module Runtime
+    # Per-connection runtime actor. Owns one transport, drives the
+    # hello/welcome handshake, dispatches inbound envelopes, and serves
+    # as the outbox queue subscriptions fan out into.
+    class SessionActor
+      attr_reader :session_id, :principal, :outbox
+
+      def initialize(runtime:, transport:)
+        @runtime = runtime
+        @transport = transport
+        @session_id = nil
+        @principal = nil
+        @outbox = Async::Queue.new
+        @last_processed_seq = 0
+        @capabilities = nil
+        @resume_token = nil
+        @heartbeat_task = nil
+        @writer_task = nil
+        @closed = false
+      end
+
+      def run
+        Async do |task|
+          envelope = @transport.receive
+          return if envelope.nil?
+
+          handshake(envelope)
+          spawn_writer(task)
+          spawn_heartbeat(task)
+          loop_inbound(task)
+        ensure
+          close_session
+        end
+      end
+
+      def send_envelope(envelope)
+        @outbox.enqueue(envelope)
+      end
+
+      private
+
+      def handshake(envelope)
+        unless envelope.type == Arcp::MessageTypes::SESSION_HELLO
+          raise Arcp::Errors::ProtocolViolation, "expected session.hello, got #{envelope.type}"
+        end
+
+        hello = Arcp::Session::Hello.from_h(envelope.payload)
+        token = hello.auth.is_a?(Hash) ? (hello.auth['token'] || hello.auth[:token]) : nil
+        @principal = @runtime.auth_verifier.verify(token)
+        if @principal.nil?
+          send_session_error(envelope.session_id, code: 'UNAUTHENTICATED', message: 'invalid bearer token')
+          raise Arcp::Errors::Unauthenticated, 'invalid bearer token'
+        end
+
+        @session_id = envelope.session_id
+        @capabilities = hello.capabilities.intersect(@runtime.local_capabilities(agents_inventory: true))
+        @resume_token = Arcp::Ids.resume_token
+
+        welcome = Arcp::Session::Welcome.new(
+          runtime_name: @runtime.name,
+          runtime_version: @runtime.version,
+          capabilities: @capabilities,
+          heartbeat_interval_sec: @runtime.heartbeat_interval_sec,
+          resume_token: @resume_token,
+          resume_window_sec: @runtime.resume_window_sec
+        )
+        out = Arcp::Envelope.build(
+          type: Arcp::MessageTypes::SESSION_WELCOME,
+          session_id: @session_id,
+          payload: welcome.to_h
+        )
+        @transport.send(out)
+        @runtime.register_session(@session_id, self)
+      rescue Arcp::Error
+        raise
+      rescue StandardError => e
+        send_session_error(envelope&.session_id || Arcp::Ids.session_id,
+                           code: 'INTERNAL_ERROR', message: e.message)
+        raise
+      end
+
+      def send_session_error(session_id, code:, message:)
+        err = Arcp::Session::SessionError.new(code: code, message: message,
+                                              retryable: false, details: {})
+        env = Arcp::Envelope.build(
+          type: Arcp::MessageTypes::SESSION_ERROR,
+          session_id: session_id, payload: err.to_h
+        )
+        @transport.send(env)
+      rescue StandardError
+        nil
+      end
+
+      def spawn_writer(parent)
+        @writer_task = parent.async do
+          loop do
+            env = @outbox.dequeue
+            break if env.nil? || env == :__arcp_close__
+
+            @transport.send(env)
+          end
+        rescue Async::Stop, IOError
+          nil
+        end
+      end
+
+      def spawn_heartbeat(parent)
+        return unless @capabilities.supports?(Arcp::Session::Feature::HEARTBEAT)
+        return if @runtime.heartbeat_interval_sec.nil?
+
+        @heartbeat_task = parent.async do |t|
+          loop do
+            t.sleep(@runtime.heartbeat_interval_sec)
+            ping = Arcp::Session::Ping.new(nonce: Arcp::Ids.envelope_id,
+                                           sent_at: @runtime.clock.now.iso8601)
+            send_envelope(Arcp::Envelope.build(
+                            type: Arcp::MessageTypes::SESSION_PING,
+                            session_id: @session_id, payload: ping.to_h
+                          ))
+          end
+        rescue Async::Stop
+          nil
+        end
+      end
+
+      def loop_inbound(_parent)
+        loop do
+          env = @transport.receive
+          break if env.nil?
+
+          dispatch(env)
+        end
+      end
+
+      def dispatch(env)
+        case env.type
+        when Arcp::MessageTypes::SESSION_BYE
+          close_session
+        when Arcp::MessageTypes::SESSION_PING
+          ping = Arcp::Session::Ping.from_h(env.payload)
+          send_envelope(Arcp::Envelope.build(
+                          type: Arcp::MessageTypes::SESSION_PONG,
+                          session_id: @session_id,
+                          payload: Arcp::Session::Pong.new(ping_nonce: ping.nonce,
+                                                           received_at: @runtime.clock.now.iso8601).to_h
+                        ))
+        when Arcp::MessageTypes::SESSION_PONG
+          nil
+        when Arcp::MessageTypes::SESSION_ACK
+          ack = Arcp::Session::Ack.from_h(env.payload)
+          @runtime.event_log.evict_up_to(@session_id, ack.last_processed_seq)
+          @last_processed_seq = ack.last_processed_seq
+        when Arcp::MessageTypes::SESSION_LIST_JOBS
+          handle_list_jobs(env)
+        when Arcp::MessageTypes::JOB_SUBMIT
+          handle_submit(env)
+        when Arcp::MessageTypes::JOB_CANCEL
+          handle_cancel(env)
+        when Arcp::MessageTypes::JOB_SUBSCRIBE
+          handle_subscribe(env)
+        when Arcp::MessageTypes::JOB_UNSUBSCRIBE
+          handle_unsubscribe(env)
+        end
+        # forward-compat: unknown wire types fall through silently.
+      rescue Arcp::Error => e
+        reply_error(env, e)
+      end
+
+      def handle_list_jobs(env)
+        unless @capabilities.supports?(Arcp::Session::Feature::LIST_JOBS)
+          raise Arcp::Errors::ProtocolViolation, 'list_jobs not negotiated'
+        end
+
+        req = Arcp::Session::ListJobs.from_h(env.payload)
+        response = @runtime.job_manager.list(
+          principal_id: @principal.id,
+          filter: req.filter, limit: req.limit || 50, cursor: req.cursor
+        )
+        send_envelope(Arcp::Envelope.build(
+                        type: Arcp::MessageTypes::SESSION_JOBS,
+                        session_id: @session_id,
+                        payload: response.to_h.merge('reply_to' => env.id)
+                      ))
+      end
+
+      def handle_submit(env)
+        submit = Arcp::Job::Submit.from_h(env.payload)
+        submit.lease_constraints&.validate!
+        result = @runtime.job_manager.submit(
+          submit: submit, principal_id: @principal.id,
+          session_id: @session_id, session_actor: self
+        )
+        if result.is_a?(Array)
+          job_id, resolved_agent, lease, credentials = result
+          accepted = Arcp::Job::Accepted.new(
+            job_id: job_id, agent: resolved_agent,
+            accepted_at: @runtime.clock.now.iso8601,
+            lease: lease,
+            credentials: credentials
+          )
+        else
+          job_id = result
+          record = @runtime.job_manager.lookup(job_id)
+          accepted = Arcp::Job::Accepted.new(
+            job_id: job_id, agent: record.agent,
+            accepted_at: record.created_at,
+            lease: @runtime.lease_manager.get(job_id),
+            credentials: nil
+          )
+        end
+        send_envelope(Arcp::Envelope.build(
+                        type: Arcp::MessageTypes::JOB_ACCEPTED,
+                        session_id: @session_id, job_id: accepted.job_id,
+                        payload: accepted.to_h.merge('reply_to' => env.id)
+                      ))
+      end
+
+      def handle_cancel(env)
+        cancel = Arcp::Job::Cancel.from_h(env.payload)
+        @runtime.job_manager.cancel(
+          job_id: cancel.job_id, principal_id: @principal.id, reason: cancel.reason
+        )
+      end
+
+      def handle_subscribe(env)
+        unless @capabilities.supports?(Arcp::Session::Feature::SUBSCRIBE)
+          raise Arcp::Errors::ProtocolViolation, 'subscribe not negotiated'
+        end
+
+        sub = Arcp::Job::Subscribe.from_h(env.payload)
+        @runtime.subscription_manager.attach(sub.job_id, @principal.id, @session_id, @outbox)
+
+        if sub.history
+          replay = @runtime.event_log.replay(@session_id, from_event_seq: sub.from_event_seq)
+          replay.each { |e| send_envelope(e) }
+        end
+
+        subscribed = Arcp::Job::Subscribed.new(
+          job_id: sub.job_id, subscribed_from: sub.from_event_seq || 0
+        )
+        send_envelope(Arcp::Envelope.build(
+                        type: Arcp::MessageTypes::JOB_SUBSCRIBED,
+                        session_id: @session_id, job_id: sub.job_id,
+                        payload: subscribed.to_h.merge('reply_to' => env.id)
+                      ))
+      end
+
+      def handle_unsubscribe(env)
+        unsub = Arcp::Job::Unsubscribe.from_h(env.payload)
+        @runtime.subscription_manager.detach(unsub.job_id, @session_id)
+      end
+
+      def reply_error(env, error)
+        if env&.job_id
+          job_err = Arcp::Job::JobError.new(
+            job_id: env.job_id, final_status: 'error',
+            code: error.code, message: error.message,
+            retryable: error.retryable?, details: error.details || {}
+          )
+          send_envelope(Arcp::Envelope.build(
+                          type: Arcp::MessageTypes::JOB_ERROR,
+                          session_id: @session_id, job_id: env.job_id,
+                          payload: job_err.to_h.merge('reply_to' => env.id)
+                        ))
+          return
+        end
+
+        err = Arcp::Session::SessionError.new(
+          code: error.code, message: error.message,
+          retryable: error.retryable?, details: error.details || {}
+        )
+        payload = err.to_h
+        payload['reply_to'] = env.id if env
+        send_envelope(Arcp::Envelope.build(
+                        type: Arcp::MessageTypes::SESSION_ERROR,
+                        session_id: @session_id || env&.session_id || '',
+                        payload: payload
+                      ))
+      end
+
+      def close_session
+        return if @closed
+
+        @closed = true
+        @heartbeat_task&.stop
+        @writer_task&.stop
+        @outbox.enqueue(:__arcp_close__)
+        @transport.close
+        @runtime.deregister_session(@session_id) if @session_id
+      end
+    end
+  end
+end

data/lib/arcp/runtime/subscription_manager.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Runtime
+    # Tracks per-job subscribers across sessions. Submitter session is
+    # registered first; additional subscribers attach via `job.subscribe`
+    # and receive a fan-out of every `job.event` and the terminating
+    # `job.result` / `job.error`.
+    class SubscriptionManager
+      def initialize
+        @subs = Hash.new { |h, k| h[k] = [] } # job_id => [[session_id, principal_id, queue], …]
+        @owners = {}                          # job_id => principal_id (submitter)
+        @mutex = Mutex.new
+      end
+
+      def register_owner(job_id, principal_id, session_id, queue)
+        @mutex.synchronize do
+          @owners[job_id] = principal_id
+          @subs[job_id] << [session_id, principal_id, queue]
+        end
+      end
+
+      def attach(job_id, principal_id, session_id, queue)
+        @mutex.synchronize do
+          unless @owners[job_id] == principal_id
+            raise Arcp::Errors::PermissionDenied.new(
+              "principal not authorized to observe #{job_id}",
+              details: { 'job_id' => job_id }
+            )
+          end
+
+          @subs[job_id] << [session_id, principal_id, queue]
+        end
+      end
+
+      def detach(job_id, session_id)
+        @mutex.synchronize do
+          @subs[job_id].reject! { |s, _, _| s == session_id }
+        end
+      end
+
+      def fanout(job_id, envelope)
+        targets = @mutex.synchronize { @subs[job_id].dup }
+        targets.each { |_s, _p, q| q.enqueue(envelope) }
+      end
+
+      def owner_of(job_id) = @mutex.synchronize { @owners[job_id] }
+
+      def clear(job_id)
+        @mutex.synchronize do
+          @subs.delete(job_id)
+          @owners.delete(job_id)
+        end
+      end
+    end
+  end
+end

data/lib/arcp/runtime.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'runtime/runtime'
+require_relative 'runtime/credential_registry'
+require_relative 'runtime/job_manager'
+require_relative 'runtime/lease_manager'
+require_relative 'runtime/subscription_manager'
+require_relative 'runtime/event_log'
+require_relative 'runtime/job_context'
+require_relative 'runtime/session_actor'

data/lib/arcp/serializer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Arcp
+  module Serializer
+    module_function
+
+    @backend = :stdlib
+
+    def backend = @backend
+
+    def backend=(name)
+      case name
+      when :stdlib, :oj
+        @backend = name
+        require 'oj' if name == :oj
+      else
+        raise ArgumentError, "unknown serializer backend: #{name.inspect}"
+      end
+    end
+
+    def dump(value)
+      case @backend
+      when :oj
+        Oj.dump(value, mode: :compat)
+      else
+        JSON.generate(value)
+      end
+    end
+
+    def load(bytes)
+      return nil if bytes.nil? || bytes.empty?
+
+      case @backend
+      when :oj
+        Oj.load(bytes, mode: :compat)
+      else
+        JSON.parse(bytes)
+      end
+    end
+  end
+end

data/lib/arcp/session/ack.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    Ack = Data.define(:last_processed_seq) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(last_processed_seq: h.fetch('last_processed_seq'))
+      end
+
+      def to_h = { 'last_processed_seq' => last_processed_seq }
+    end
+  end
+end

data/lib/arcp/session/agent_inventory.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    AgentEntry = Data.define(:name, :versions, :default) do
+      def self.from_hash(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          name: h.fetch('name'),
+          versions: Array(h['versions']).map(&:to_s).freeze,
+          default: h['default']
+        )
+      end
+
+      def to_h
+        h = { 'name' => name, 'versions' => versions }
+        h['default'] = default if default
+        h
+      end
+    end
+
+    AgentInventory = Data.define(:entries) do
+      include Enumerable
+
+      def self.from_array(arr)
+        new(entries: arr.map { |h| AgentEntry.from_hash(h) }.freeze)
+      end
+
+      def each(&) = entries.each(&)
+      def to_a = entries.map(&:to_h)
+
+      def find(name) = entries.find { |e| e.name == name }
+      def default_for(name) = find(name)&.default
+      def versions_for(name) = find(name)&.versions || [].freeze
+      def names = entries.map(&:name)
+
+      def resolve(ref)
+        name, version = ref.to_s.split('@', 2)
+        entry = find(name)
+        return nil unless entry
+
+        version ||= entry.default
+        return nil unless version
+
+        return nil unless entry.versions.empty? || entry.versions.include?(version)
+
+        "#{name}@#{version}"
+      end
+    end
+  end
+end

data/lib/arcp/session/bye.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    Bye = Data.define(:reason) do
+      def self.from_h(h) = new(reason: h.transform_keys(&:to_s)['reason'])
+      def to_h = { 'reason' => reason }.compact
+    end
+  end
+end

data/lib/arcp/session/capability_set.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    CapabilitySet = Data.define(:features, :encodings, :agents) do
+      DEFAULT_ENCODINGS = %w[utf8 base64].freeze
+
+      def self.local(features: Feature::ALL, encodings: DEFAULT_ENCODINGS, agents: nil)
+        new(features: features.dup.freeze, encodings: encodings.dup.freeze, agents: agents)
+      end
+
+      def intersect(other)
+        self.class.new(
+          features: (features & other.features).freeze,
+          encodings: (encodings & other.encodings).freeze,
+          agents: other.agents || agents
+        )
+      end
+
+      def supports?(feature) = features.include?(feature)
+
+      def to_h
+        h = { 'features' => features, 'encodings' => encodings }
+        h['agents'] = agents.to_a if agents
+        h
+      end
+    end
+  end
+end

data/lib/arcp/session/feature.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    module Feature
+      HEARTBEAT        = 'heartbeat'
+      ACK              = 'ack'
+      LIST_JOBS        = 'list_jobs'
+      SUBSCRIBE        = 'subscribe'
+      LEASE_EXPIRES_AT = 'lease_expires_at'
+      COST_BUDGET      = 'cost.budget'
+      PROGRESS         = 'progress'
+      RESULT_CHUNK     = 'result_chunk'
+      AGENT_VERSIONS   = 'agent_versions'
+      MODEL_USE        = 'model.use'
+      PROVISIONED_CREDENTIALS = 'provisioned_credentials'
+
+      ALL = [
+        HEARTBEAT, ACK, LIST_JOBS, SUBSCRIBE, LEASE_EXPIRES_AT,
+        COST_BUDGET, PROGRESS, RESULT_CHUNK, AGENT_VERSIONS,
+        MODEL_USE, PROVISIONED_CREDENTIALS
+      ].freeze
+    end
+  end
+end

data/lib/arcp/session/hello.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    Hello = Data.define(:client_name, :client_version, :auth, :capabilities, :resume) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        caps = h['capabilities'] || {}
+        new(
+          client_name: h['client_name'],
+          client_version: h['client_version'],
+          auth: h['auth'] || {},
+          capabilities: CapabilitySet.new(
+            features: Array(caps['features']).freeze,
+            encodings: Array(caps['encodings']).freeze,
+            agents: nil
+          ),
+          resume: h['resume']
+        )
+      end
+
+      def to_h
+        h = {
+          'client_name' => client_name,
+          'client_version' => client_version,
+          'auth' => auth,
+          'capabilities' => capabilities.to_h.except('agents')
+        }
+        h['resume'] = resume if resume
+        h
+      end
+    end
+  end
+end

data/lib/arcp/session/jobs_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    JobsResponse = Data.define(:jobs, :next_cursor) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(jobs: Array(h['jobs']).map(&:freeze).freeze, next_cursor: h['next_cursor'])
+      end
+
+      def to_h
+        out = { 'jobs' => jobs }
+        out['next_cursor'] = next_cursor if next_cursor
+        out
+      end
+    end
+  end
+end

data/lib/arcp/session/list_jobs.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    ListJobs = Data.define(:filter, :limit, :cursor) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(filter: h['filter'] || {}, limit: h['limit'], cursor: h['cursor'])
+      end
+
+      def to_h
+        out = { 'filter' => filter || {} }
+        out['limit'] = limit if limit
+        out['cursor'] = cursor if cursor
+        out
+      end
+    end
+  end
+end

data/lib/arcp/session/ping.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    Ping = Data.define(:nonce, :sent_at) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(nonce: h.fetch('nonce'), sent_at: h.fetch('sent_at'))
+      end
+
+      def to_h = { 'nonce' => nonce, 'sent_at' => sent_at }
+    end
+  end
+end

data/lib/arcp/session/pong.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    Pong = Data.define(:ping_nonce, :received_at) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(ping_nonce: h.fetch('ping_nonce'), received_at: h.fetch('received_at'))
+      end
+
+      def to_h = { 'ping_nonce' => ping_nonce, 'received_at' => received_at }
+    end
+  end
+end

data/lib/arcp/session/session_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    SessionError = Data.define(:code, :message, :retryable, :details) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          code: h.fetch('code'),
+          message: h['message'],
+          retryable: h.fetch('retryable', false),
+          details: h['details'] || {}
+        )
+      end
+
+      def to_h
+        h = { 'code' => code, 'message' => message, 'retryable' => retryable }
+        h['details'] = details unless details.nil? || details.empty?
+        h
+      end
+    end
+  end
+end