arcp 1.0.0

data/lib/arcp/errors.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Arcp
+  class Error < StandardError
+    CODE = 'INTERNAL_ERROR'
+
+    attr_reader :details
+
+    def initialize(message = nil, details: {})
+      @details = details.freeze
+      super(message || self.class.default_message)
+    end
+
+    def code = self.class::CODE
+    def retryable? = false
+
+    def to_payload(trace_id: nil)
+      payload = { code: code, message: message, retryable: retryable? }
+      payload[:details] = details unless details.empty?
+      payload[:trace_id] = trace_id if trace_id
+      payload
+    end
+
+    def self.default_message = name.split('::').last.gsub(/([a-z])([A-Z])/, '\1 \2').downcase
+  end
+
+  module Errors
+    class Cancelled < Arcp::Error
+      CODE = 'CANCELLED'
+    end
+
+    class InvalidRequest < Arcp::Error
+      CODE = 'INVALID_REQUEST'
+    end
+
+    class Unauthenticated < Arcp::Error
+      CODE = 'UNAUTHENTICATED'
+    end
+
+    class PermissionDenied < Arcp::Error
+      CODE = 'PERMISSION_DENIED'
+    end
+
+    class JobNotFound < Arcp::Error
+      CODE = 'JOB_NOT_FOUND'
+    end
+
+    class AgentNotAvailable < Arcp::Error
+      CODE = 'AGENT_NOT_AVAILABLE'
+      def retryable? = true
+    end
+
+    class DuplicateKey < Arcp::Error
+      CODE = 'DUPLICATE_KEY'
+    end
+
+    class RateLimited < Arcp::Error
+      CODE = 'RATE_LIMITED'
+      def retryable? = true
+    end
+
+    class Internal < Arcp::Error
+      CODE = 'INTERNAL_ERROR'
+      def retryable? = true
+    end
+
+    class HeartbeatLost < Arcp::Error
+      CODE = 'HEARTBEAT_LOST'
+      def retryable? = true
+    end
+
+    class Backpressure < Arcp::Error
+      CODE = 'BACKPRESSURE'
+      def retryable? = true
+    end
+
+    class ProtocolViolation < Arcp::Error
+      CODE = 'PROTOCOL_VIOLATION'
+    end
+
+    class Timeout < Arcp::Error
+      CODE = 'TIMEOUT'
+      def retryable? = true
+    end
+
+    class ResumeWindowExpired < Arcp::Error
+      CODE = 'RESUME_WINDOW_EXPIRED'
+    end
+
+    class LeaseSubsetViolation < Arcp::Error
+      CODE = 'LEASE_SUBSET_VIOLATION'
+    end
+
+    class AgentVersionNotAvailable < Arcp::Error
+      CODE = 'AGENT_VERSION_NOT_AVAILABLE'
+    end
+
+    class LeaseExpired < Arcp::Error
+      CODE = 'LEASE_EXPIRED'
+    end
+
+    class BudgetExhausted < Arcp::Error
+      CODE = 'BUDGET_EXHAUSTED'
+    end
+
+    # Library-internal: never appears on the wire.
+    class UnnegotiatedFeature < Arcp::Error
+      CODE = 'UNNEGOTIATED_FEATURE'
+    end
+
+    ALL = [
+      Cancelled, InvalidRequest, Unauthenticated, PermissionDenied,
+      JobNotFound, AgentNotAvailable, DuplicateKey, RateLimited,
+      Internal, HeartbeatLost, Backpressure, ProtocolViolation, Timeout,
+      ResumeWindowExpired, LeaseSubsetViolation,
+      AgentVersionNotAvailable, LeaseExpired, BudgetExhausted
+    ].freeze
+
+    WIRE_CODES = ALL.map { |c| c::CODE }.freeze
+
+    BY_CODE = ALL.to_h { |klass| [klass::CODE, klass] }.freeze
+
+    RETRYABLE_BY_DEFAULT = ALL.select { |k| k.new.retryable? }.map { |k| k::CODE }.freeze
+    NON_RETRYABLE_BY_DEFAULT = (WIRE_CODES - RETRYABLE_BY_DEFAULT).freeze
+
+    def self.for(code, message: nil, details: {})
+      klass = BY_CODE[code] || Arcp::Errors::Internal
+      klass.new(message, details: details)
+    end
+  end
+
+  module ErrorCode
+    CANCELLED                    = 'CANCELLED'
+    INVALID_REQUEST              = 'INVALID_REQUEST'
+    UNAUTHENTICATED              = 'UNAUTHENTICATED'
+    PERMISSION_DENIED            = 'PERMISSION_DENIED'
+    JOB_NOT_FOUND                = 'JOB_NOT_FOUND'
+    AGENT_NOT_AVAILABLE          = 'AGENT_NOT_AVAILABLE'
+    DUPLICATE_KEY                = 'DUPLICATE_KEY'
+    RATE_LIMITED                 = 'RATE_LIMITED'
+    INTERNAL_ERROR               = 'INTERNAL_ERROR'
+    HEARTBEAT_LOST               = 'HEARTBEAT_LOST'
+    BACKPRESSURE                 = 'BACKPRESSURE'
+    PROTOCOL_VIOLATION           = 'PROTOCOL_VIOLATION'
+    TIMEOUT                      = 'TIMEOUT'
+    RESUME_WINDOW_EXPIRED        = 'RESUME_WINDOW_EXPIRED'
+    LEASE_SUBSET_VIOLATION       = 'LEASE_SUBSET_VIOLATION'
+    AGENT_VERSION_NOT_AVAILABLE  = 'AGENT_VERSION_NOT_AVAILABLE'
+    LEASE_EXPIRED                = 'LEASE_EXPIRED'
+    BUDGET_EXHAUSTED             = 'BUDGET_EXHAUSTED'
+
+    ALL = Arcp::Errors::WIRE_CODES
+  end
+end

data/lib/arcp/ids.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Arcp
+  module Ids
+    module_function
+
+    def envelope_id = SecureRandom.uuid_v7
+    def session_id  = "ses_#{SecureRandom.uuid_v7}"
+    def job_id      = "job_#{SecureRandom.uuid_v7}"
+    def result_id   = "res_#{SecureRandom.uuid_v7}"
+    def call_id     = "call_#{SecureRandom.uuid_v7}"
+    def resume_token = SecureRandom.urlsafe_base64(24)
+    def trace_id    = SecureRandom.hex(16)
+    def span_id     = SecureRandom.hex(8)
+  end
+end

data/lib/arcp/job/accepted.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../credential'
+
+module Arcp
+  module Job
+    Accepted = Data.define(:job_id, :agent, :accepted_at, :lease, :credentials) do
+      def initialize(job_id:, agent:, accepted_at:, lease: nil, credentials: nil)
+        super
+      end
+
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          job_id: h.fetch('job_id'),
+          agent: h.fetch('agent'),
+          accepted_at: h['accepted_at'],
+          lease: h['lease'] ? Arcp::Lease::Lease.from_h(h['lease']) : nil,
+          credentials: credentials_from(h)
+        )
+      end
+
+      def to_h
+        out = { 'job_id' => job_id, 'agent' => agent, 'accepted_at' => accepted_at }
+        out['lease'] = lease.to_h if lease
+        out['credentials'] = credentials.map(&:to_h) if credentials && !credentials.empty?
+        out
+      end
+
+      def self.credentials_from(h)
+        return nil unless h['credentials']
+
+        Array(h['credentials']).map { |credential| Arcp::Credential.from_h(credential) }.freeze
+      end
+    end
+  end
+end

data/lib/arcp/job/agent_ref.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    AgentRef = Data.define(:name, :version) do
+      def self.parse(ref)
+        return nil if ref.nil?
+
+        name, version = ref.to_s.split('@', 2)
+        raise Arcp::Errors::InvalidRequest, 'agent name must be non-empty' if name.nil? || name.empty?
+
+        new(name: name, version: version)
+      end
+
+      def to_s = version ? "#{name}@#{version}" : name
+    end
+  end
+end

data/lib/arcp/job/cancel.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    Cancel = Data.define(:job_id, :reason) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(job_id: h.fetch('job_id'), reason: h['reason'])
+      end
+
+      def to_h
+        out = { 'job_id' => job_id }
+        out['reason'] = reason if reason
+        out
+      end
+    end
+  end
+end

data/lib/arcp/job/event.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Body classes live in `Arcp::Job::EventBody`. The `Event` constant
+# below is a `Data.define` value object — it cannot also be a module,
+# so the per-kind body types are namespaced separately.
+require_relative 'event_body/progress'
+require_relative 'event_body/result_chunk'
+require_relative 'event_body/log'
+require_relative 'event_body/thought'
+require_relative 'event_body/tool_call'
+require_relative 'event_body/tool_result'
+require_relative 'event_body/status'
+require_relative 'event_body/metric'
+require_relative 'event_body/trace_span'
+require_relative 'event_body/delegate'
+
+module Arcp
+  module Job
+    module EventKind
+      PROGRESS     = 'progress'
+      RESULT_CHUNK = 'result_chunk'
+      LOG          = 'log'
+      THOUGHT      = 'thought'
+      TOOL_CALL    = 'tool_call'
+      TOOL_RESULT  = 'tool_result'
+      STATUS       = 'status'
+      METRIC       = 'metric'
+      TRACE_SPAN   = 'trace_span'
+      DELEGATE     = 'delegate'
+
+      ALL = [
+        PROGRESS, RESULT_CHUNK, LOG, THOUGHT, TOOL_CALL, TOOL_RESULT,
+        STATUS, METRIC, TRACE_SPAN, DELEGATE
+      ].freeze
+    end
+
+    BODY_CLASSES = {
+      EventKind::PROGRESS => EventBody::Progress,
+      EventKind::RESULT_CHUNK => EventBody::ResultChunk,
+      EventKind::LOG => EventBody::Log,
+      EventKind::THOUGHT => EventBody::Thought,
+      EventKind::TOOL_CALL => EventBody::ToolCall,
+      EventKind::TOOL_RESULT => EventBody::ToolResult,
+      EventKind::STATUS => EventBody::Status,
+      EventKind::METRIC => EventBody::Metric,
+      EventKind::TRACE_SPAN => EventBody::TraceSpan,
+      EventKind::DELEGATE => EventBody::Delegate
+    }.freeze
+
+    Event = Data.define(:kind, :body) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        kind = h.fetch('kind')
+        body_h = h['body'] || {}
+        klass = BODY_CLASSES[kind]
+        body = klass ? klass.from_h(body_h) : Arcp::Envelope.deep_freeze(body_h.dup)
+        new(kind: kind, body: body)
+      end
+
+      def to_h
+        body_h = body.respond_to?(:to_h) ? body.to_h : body
+        { 'kind' => kind, 'body' => body_h }
+      end
+
+      def known? = EventKind::ALL.include?(kind)
+    end
+  end
+end

data/lib/arcp/job/event_body/delegate.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      Delegate = Data.define(:child_job_id, :agent, :lease) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(
+            child_job_id: h.fetch('child_job_id'),
+            agent: h.fetch('agent'),
+            lease: h['lease'] ? Arcp::Lease::Lease.from_h(h['lease']) : nil
+          )
+        end
+
+        def to_h
+          out = { 'child_job_id' => child_job_id, 'agent' => agent }
+          out['lease'] = lease.to_h if lease
+          out
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/log.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      Log = Data.define(:level, :message, :fields) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(level: h.fetch('level'), message: h.fetch('message'), fields: h['fields'] || {})
+        end
+
+        def to_h
+          out = { 'level' => level, 'message' => message }
+          out['fields'] = fields unless fields.empty?
+          out
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/metric.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      Metric = Data.define(:name, :value, :unit) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(name: h.fetch('name'), value: h.fetch('value'), unit: h['unit'])
+        end
+
+        def to_h
+          out = { 'name' => name, 'value' => value }
+          out['unit'] = unit if unit
+          out
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/progress.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      Progress = Data.define(:current, :total, :units, :message) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(
+            current: h.fetch('current'),
+            total: h['total'],
+            units: h['units'],
+            message: h['message']
+          )
+        end
+
+        def to_h
+          out = { 'current' => current }
+          out['total']   = total if total
+          out['units']   = units if units
+          out['message'] = message if message
+          out
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/result_chunk.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Arcp
+  module Job
+    module EventBody
+      ResultChunk = Data.define(:result_id, :chunk_seq, :data, :encoding, :more) do
+        ENCODINGS = %w[utf8 base64].freeze
+
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          encoding = h.fetch('encoding')
+          unless ENCODINGS.include?(encoding)
+            raise Arcp::Errors::InvalidRequest,
+                  "unknown encoding: #{encoding.inspect}"
+          end
+
+          new(
+            result_id: h.fetch('result_id'),
+            chunk_seq: h.fetch('chunk_seq'),
+            data: h.fetch('data'),
+            encoding: encoding,
+            more: h.fetch('more')
+          )
+        end
+
+        def to_h
+          { 'result_id' => result_id, 'chunk_seq' => chunk_seq, 'data' => data,
+            'encoding' => encoding, 'more' => more }
+        end
+
+        def decoded
+          case encoding
+          when 'utf8'   then data
+          when 'base64' then Base64.decode64(data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/status.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      Status = Data.define(:phase, :message, :fields) do
+        def initialize(phase:, message: nil, fields: {})
+          super(phase: phase, message: message, fields: fields || {})
+        end
+
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(phase: h.fetch('phase'), message: h['message'], fields: h['fields'] || {})
+        end
+
+        def to_h
+          out = { 'phase' => phase }
+          out['message'] = message if message
+          out['fields'] = fields unless fields.empty?
+          out
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/thought.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      Thought = Data.define(:text) do
+        def self.from_h(h) = new(text: h.transform_keys(&:to_s).fetch('text'))
+        def to_h = { 'text' => text }
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/tool_call.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      ToolCall = Data.define(:call_id, :tool, :args) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(call_id: h.fetch('call_id'), tool: h.fetch('tool'), args: h['args'] || {})
+        end
+
+        def to_h = { 'call_id' => call_id, 'tool' => tool, 'args' => args }
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/tool_result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      ToolResult = Data.define(:call_id, :result, :error) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(call_id: h.fetch('call_id'), result: h['result'], error: h['error'])
+        end
+
+        def to_h
+          out = { 'call_id' => call_id }
+          out['result'] = result if result
+          out['error']  = error if error
+          out
+        end
+
+        def ok? = error.nil?
+      end
+    end
+  end
+end

data/lib/arcp/job/event_body/trace_span.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    module EventBody
+      TraceSpan = Data.define(:span_id, :parent_span_id, :name, :start_at, :end_at, :attributes) do
+        def self.from_h(h)
+          h = h.transform_keys(&:to_s)
+          new(
+            span_id: h.fetch('span_id'),
+            parent_span_id: h['parent_span_id'],
+            name: h.fetch('name'),
+            start_at: h['start_at'],
+            end_at: h['end_at'],
+            attributes: h['attributes'] || {}
+          )
+        end
+
+        def to_h
+          out = { 'span_id' => span_id, 'name' => name }
+          out['parent_span_id'] = parent_span_id if parent_span_id
+          out['start_at']       = start_at if start_at
+          out['end_at']         = end_at if end_at
+          out['attributes']     = attributes unless attributes.empty?
+          out
+        end
+      end
+    end
+  end
+end

data/lib/arcp/job/handle.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    Handle = Data.define(:job_id, :agent, :submitted_at, :lease, :credentials) do
+      def initialize(job_id:, agent:, submitted_at:, lease: nil, credentials: nil)
+        super
+      end
+
+      def subscribe(client:, **kw) = client.subscribe_job(job_id: job_id, **kw)
+      def cancel(client:, reason: nil) = client.cancel_job(job_id: job_id, reason: reason)
+      def get_result(client:) = client.get_result(job_id: job_id)
+      def credential_for(endpoint:) = Array(credentials).find { |credential| credential.endpoint == endpoint }
+    end
+  end
+end

data/lib/arcp/job/job_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    JobError = Data.define(:job_id, :final_status, :code, :message, :retryable, :details) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          job_id: h.fetch('job_id'),
+          final_status: h.fetch('final_status'),
+          code: h.fetch('code'),
+          message: h['message'],
+          retryable: h.fetch('retryable', false),
+          details: h['details'] || {}
+        )
+      end
+
+      def to_h
+        out = { 'job_id' => job_id, 'final_status' => final_status,
+                'code' => code, 'retryable' => retryable }
+        out['message'] = message if message
+        out['details'] = details unless details.empty?
+        out
+      end
+
+      def to_exception
+        Arcp::Errors.for(code, message: message, details: details)
+      end
+    end
+  end
+end

data/lib/arcp/job/result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    Result = Data.define(:job_id, :final_status, :result, :result_id, :result_size, :completed_at) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          job_id: h.fetch('job_id'),
+          final_status: h.fetch('final_status'),
+          result: h['result'],
+          result_id: h['result_id'],
+          result_size: h['result_size'],
+          completed_at: h['completed_at']
+        )
+      end
+
+      def to_h
+        out = { 'job_id' => job_id, 'final_status' => final_status }
+        out['result']       = result if result
+        out['result_id']    = result_id if result_id
+        out['result_size']  = result_size if result_size
+        out['completed_at'] = completed_at if completed_at
+        out
+      end
+
+      def chunked? = !result_id.nil?
+    end
+  end
+end

data/lib/arcp/job/submit.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Job
+    Submit = Data.define(
+      :agent, :input, :lease_request, :lease_constraints,
+      :idempotency_key, :max_runtime_sec
+    ) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          agent: h.fetch('agent'),
+          input: h['input'],
+          lease_request: Arcp::Lease::LeaseRequest.from_h(h['lease_request']),
+          lease_constraints: Arcp::Lease::LeaseConstraints.from_h(h['lease_constraints']),
+          idempotency_key: h['idempotency_key'],
+          max_runtime_sec: h['max_runtime_sec']
+        )
+      end
+
+      def to_h
+        out = { 'agent' => agent }
+        out['input'] = input if input
+        out['lease_request']     = lease_request.to_h if lease_request
+        out['lease_constraints'] = lease_constraints.to_h if lease_constraints
+        out['idempotency_key']   = idempotency_key if idempotency_key
+        out['max_runtime_sec']   = max_runtime_sec if max_runtime_sec
+        out
+      end
+    end
+  end
+end