arcp 1.0.0

data/lib/arcp/session/welcome.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Session
+    Welcome = Data.define(
+      :runtime_name, :runtime_version, :capabilities,
+      :heartbeat_interval_sec, :resume_token, :resume_window_sec
+    ) do
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        caps = h['capabilities'] || {}
+        new(
+          runtime_name: h['runtime_name'],
+          runtime_version: h['runtime_version'],
+          capabilities: CapabilitySet.new(
+            features: Array(caps['features']).freeze,
+            encodings: Array(caps['encodings']).freeze,
+            agents: caps['agents'] ? AgentInventory.from_array(caps['agents']) : nil
+          ),
+          heartbeat_interval_sec: h['heartbeat_interval_sec'],
+          resume_token: h['resume_token'],
+          resume_window_sec: h['resume_window_sec']
+        )
+      end
+
+      def to_h
+        {
+          'runtime_name' => runtime_name,
+          'runtime_version' => runtime_version,
+          'capabilities' => capabilities.to_h,
+          'heartbeat_interval_sec' => heartbeat_interval_sec,
+          'resume_token' => resume_token,
+          'resume_window_sec' => resume_window_sec
+        }
+      end
+    end
+  end
+end

data/lib/arcp/session.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'session/feature'
+require_relative 'session/capability_set'
+require_relative 'session/agent_inventory'
+require_relative 'session/hello'
+require_relative 'session/welcome'
+require_relative 'session/bye'
+require_relative 'session/session_error'
+require_relative 'session/ping'
+require_relative 'session/pong'
+require_relative 'session/ack'
+require_relative 'session/list_jobs'
+require_relative 'session/jobs_response'
+
+module Arcp
+  module Session
+    # Immutable snapshot of session state after the welcome envelope.
+    Info = Data.define(
+      :id, :runtime_version, :capabilities, :agents,
+      :heartbeat_interval_sec, :resume_token, :resume_window_sec
+    ) do
+      def supports?(feature) = capabilities.supports?(feature)
+    end
+  end
+end

data/lib/arcp/trace.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'ids'
+
+module Arcp
+  module Trace
+    KEY = :arcp_trace_context
+
+    Context = Data.define(:trace_id, :span_id, :attributes)
+
+    module_function
+
+    def current
+      Fiber[KEY] || Context.new(trace_id: nil, span_id: nil, attributes: {}.freeze)
+    end
+
+    def current=(ctx)
+      Fiber[KEY] = ctx
+    end
+
+    def with(trace_id: nil, span_id: nil, attributes: {})
+      prev = current
+      Fiber[KEY] = Context.new(
+        trace_id: trace_id || prev.trace_id || Arcp::Ids.trace_id,
+        span_id: span_id || Arcp::Ids.span_id,
+        attributes: prev.attributes.merge(attributes).freeze
+      )
+      yield current
+    ensure
+      Fiber[KEY] = prev
+    end
+
+    # @return [String] new 32-hex trace id.
+    def new_trace_id = Arcp::Ids.trace_id
+
+    def in_span(name, attributes: {}, &)
+      tracer = begin
+        require 'opentelemetry'
+        OpenTelemetry.tracer_provider.tracer('arcp')
+      rescue LoadError
+        nil
+      end
+
+      if tracer
+        tracer.in_span(name, attributes: attributes, &)
+      else
+        with(attributes: attributes, &)
+      end
+    end
+  end
+end

data/lib/arcp/transport/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../envelope'
+
+module Arcp
+  module Transport
+    # Abstract transport interface. Implementations carry frames, not
+    # message types — decoding is `Arcp::Envelope.from_h`.
+    #
+    # `#send` accepts an `Arcp::Envelope` and serializes it.
+    # `#receive` suspends the calling fiber until an envelope arrives,
+    # then returns it (or nil on clean close).
+    class Base
+      def send(envelope)
+        raise NotImplementedError
+      end
+
+      def receive
+        raise NotImplementedError
+      end
+
+      def close(reason: nil)
+        raise NotImplementedError
+      end
+
+      def closed? = false
+    end
+  end
+end

data/lib/arcp/transport/memory_transport.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'async/queue'
+
+module Arcp
+  module Transport
+    # In-process transport backed by a pair of `Async::Queue`s. Used for
+    # tests and same-process server/client wiring.
+    class MemoryTransport < Base
+      attr_reader :sent
+
+      def initialize(incoming:, outgoing:)
+        super()
+        @incoming = incoming
+        @outgoing = outgoing
+        @sent = []
+        @closed = false
+      end
+
+      def self.pair
+        a = Async::Queue.new
+        b = Async::Queue.new
+        [new(incoming: a, outgoing: b), new(incoming: b, outgoing: a)]
+      end
+
+      def send(envelope)
+        raise IOError, 'transport closed' if @closed
+
+        @sent << envelope
+        @outgoing.enqueue(envelope)
+        nil
+      end
+
+      def receive
+        return nil if @closed && @incoming.empty?
+
+        value = @incoming.dequeue
+        return nil if value.equal?(:__arcp_close__)
+
+        value
+      end
+
+      def close(reason: nil)
+        return if @closed
+
+        @closed = true
+        @outgoing.enqueue(:__arcp_close__)
+        @incoming.enqueue(:__arcp_close__) if @incoming.empty?
+      end
+
+      def closed? = @closed
+    end
+  end
+end

data/lib/arcp/transport/stdio_transport.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../serializer'
+
+module Arcp
+  module Transport
+    # Newline-delimited JSON over a pair of IOs. The child process reads
+    # from stdin and writes to stdout; the parent connects with its
+    # pipe ends. Exit on EOF.
+    class StdioTransport < Base
+      def initialize(input: $stdin, output: $stdout)
+        super()
+        @input = input
+        @output = output
+        @closed = false
+        @write_mutex = Mutex.new
+      end
+
+      def send(envelope)
+        raise IOError, 'transport closed' if @closed
+
+        line = Arcp::Serializer.dump(envelope.to_h)
+        @write_mutex.synchronize do
+          @output.write(line)
+          @output.write("\n")
+          @output.flush
+        end
+        nil
+      end
+
+      def receive
+        return nil if @closed
+
+        line = @input.gets
+        if line.nil?
+          @closed = true
+          return nil
+        end
+
+        Arcp::Envelope.from_json(line)
+      end
+
+      def close(reason: nil)
+        return if @closed
+
+        @closed = true
+        @output.close unless @output.closed? || @output == $stdout
+        @input.close unless @input.closed? || @input == $stdin
+      rescue IOError
+        nil
+      end
+
+      def closed? = @closed
+    end
+  end
+end

data/lib/arcp/transport/websocket_transport.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../serializer'
+
+module Arcp
+  module Transport
+    # WebSocket transport built on `async-websocket`. The `connection`
+    # argument is an open `Async::WebSocket::Connection`.
+    class WebSocketTransport < Base
+      def initialize(connection:)
+        super()
+        @connection = connection
+        @closed = false
+      end
+
+      def send(envelope)
+        raise IOError, 'transport closed' if @closed
+
+        @connection.write(envelope.to_json)
+        @connection.flush if @connection.respond_to?(:flush)
+        nil
+      end
+
+      def receive
+        message = @connection.read
+        return nil if message.nil?
+
+        bytes = message.respond_to?(:buffer) ? message.buffer : message.to_s
+        Arcp::Envelope.from_json(bytes)
+      rescue EOFError
+        @closed = true
+        nil
+      end
+
+      def close(reason: nil)
+        return if @closed
+
+        @closed = true
+        @connection.close if @connection.respond_to?(:close)
+      rescue StandardError
+        nil
+      end
+
+      def closed? = @closed
+    end
+  end
+end

data/lib/arcp/transport.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'transport/base'
+require_relative 'transport/memory_transport'
+require_relative 'transport/stdio_transport'
+require_relative 'transport/websocket_transport'

data/lib/arcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Arcp
+  VERSION = '1.0.0'
+  PROTOCOL_VERSION = '1.1'
+  SUBPROTOCOL = 'arcp.v1'
+end

data/lib/arcp.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'arcp/version'
+require_relative 'arcp/ids'
+require_relative 'arcp/clock'
+require_relative 'arcp/errors'
+require_relative 'arcp/serializer'
+require_relative 'arcp/message_types'
+require_relative 'arcp/envelope'
+require_relative 'arcp/trace'
+require_relative 'arcp/lease'
+require_relative 'arcp/credential'
+require_relative 'arcp/credential_provisioner'
+require_relative 'arcp/session'
+require_relative 'arcp/job'
+require_relative 'arcp/auth'
+require_relative 'arcp/transport'
+require_relative 'arcp/client'
+require_relative 'arcp/runtime'

data/sig/arcp/client.rbs

@@ -0,0 +1,16 @@
+module Arcp
+  class Client
+    attr_reader session: Arcp::Session::Info
+    attr_reader transport: Arcp::Transport::Base
+
+    def self.open: (transport: Arcp::Transport::Base, auth: Hash[String, untyped], ?client_name: String, ?client_version: String, ?capabilities: Arcp::Session::CapabilitySet?, ?resume: Hash[String, untyped]?, ?clock: untyped) -> Client
+
+    def list_jobs: (?status: untyped, ?agent: String?, ?created_after: String?, ?limit: Integer?, ?cursor: String?) -> Enumerator::Lazy[Arcp::Job::Summary, untyped]
+    def submit_job: (agent: String, ?input: untyped, ?lease_request: Arcp::Lease::LeaseRequest?, ?lease_constraints: Arcp::Lease::LeaseConstraints?, ?idempotency_key: String?, ?max_runtime_sec: Integer?) -> Arcp::Job::Handle
+    def subscribe_job: (job_id: String, ?from_event_seq: Integer?, ?history: bool) -> Enumerator[Arcp::Job::Event, void]
+    def cancel_job: (job_id: String, ?reason: String?) -> Arcp::Envelope
+    def get_result: (job_id: String) -> Arcp::Job::Result
+    def ack: (Integer) -> void
+    def close: (?reason: String?) -> void
+  end
+end

data/sig/arcp/credential.rbs

@@ -0,0 +1,51 @@
+module Arcp
+  class Credential
+    SCHEME_BEARER: String
+
+    attr_reader id: String
+    attr_reader scheme: String
+    attr_reader value: String
+    attr_reader endpoint: String
+    attr_reader profile: String?
+    attr_reader constraints: Hash[String, untyped]
+
+    def self.from_h: (Hash[String | Symbol, untyped]) -> Credential
+    def to_h: () -> Hash[String, untyped]
+    def to_redacted_h: () -> Hash[String, untyped]
+  end
+
+  module ModelPattern
+    def self.match?: (Array[String]?, String) -> bool
+    def self.implied_by?: (Array[String]?, String) -> bool
+  end
+
+  module CredentialProvisioner
+    def issue: (lease: Arcp::Lease::Lease?, job_id: String, agent: String, principal_id: String) -> Array[Credential]
+    def revoke: (credential_id: String) -> void
+  end
+
+  module Credentials
+    def self.translate_upstream_error: (StandardError) -> StandardError
+    def self.budget_exhausted?: (StandardError) -> bool
+
+    class InMemoryProvisioner
+      include CredentialProvisioner
+
+      attr_reader issued: Array[Hash[Symbol, untyped]]
+      attr_reader revoked: Array[String]
+
+      def initialize: (?endpoint: String, ?profile: String) -> void
+    end
+
+    class CredentialStore
+      def record: (job_id: String, credential_id: String) -> void
+      def forget: (job_id: String, credential_id: String) -> void
+      def outstanding: (job_id: String) -> Array[String]
+      def all_outstanding: () -> Hash[String, Array[String]]
+    end
+
+    class InMemoryStore < CredentialStore
+      def initialize: () -> void
+    end
+  end
+end

data/sig/arcp/envelope.rbs

@@ -0,0 +1,25 @@
+module Arcp
+  class Envelope
+    attr_reader arcp: String
+    attr_reader id: String
+    attr_reader type: String
+    attr_reader session_id: String
+    attr_reader trace_id: String?
+    attr_reader job_id: String?
+    attr_reader event_seq: Integer?
+    attr_reader payload: Hash[String, untyped]
+
+    def self.build: (type: String, session_id: String, payload: Hash[String | Symbol, untyped], ?trace_id: String?, ?job_id: String?, ?event_seq: Integer?, ?id: String?) -> Envelope
+    def self.from_h: (Hash[String | Symbol, untyped]) -> Envelope
+    def self.from_json: (String) -> Envelope
+    def to_h: () -> Hash[String, untyped]
+    def to_json: (*untyped) -> String
+    def known?: () -> bool
+  end
+
+  class UnknownEnvelope
+    attr_reader envelope: Envelope
+    def type: () -> String
+    def payload: () -> Hash[String, untyped]
+  end
+end

data/sig/arcp/errors.rbs

@@ -0,0 +1,40 @@
+module Arcp
+  class Error < StandardError
+    CODE: String
+    attr_reader details: Hash[untyped, untyped]
+    def initialize: (?String?, ?details: Hash[untyped, untyped]) -> void
+    def code: () -> String
+    def retryable?: () -> bool
+    def to_payload: (?trace_id: String?) -> Hash[Symbol, untyped]
+  end
+
+  module Errors
+    class Cancelled < Arcp::Error end
+    class InvalidRequest < Arcp::Error end
+    class Unauthenticated < Arcp::Error end
+    class PermissionDenied < Arcp::Error end
+    class JobNotFound < Arcp::Error end
+    class AgentNotAvailable < Arcp::Error end
+    class DuplicateKey < Arcp::Error end
+    class RateLimited < Arcp::Error end
+    class Internal < Arcp::Error end
+    class HeartbeatLost < Arcp::Error end
+    class Backpressure < Arcp::Error end
+    class ProtocolViolation < Arcp::Error end
+    class Timeout < Arcp::Error end
+    class ResumeWindowExpired < Arcp::Error end
+    class LeaseSubsetViolation < Arcp::Error end
+    class AgentVersionNotAvailable < Arcp::Error end
+    class LeaseExpired < Arcp::Error end
+    class BudgetExhausted < Arcp::Error end
+    class UnnegotiatedFeature < Arcp::Error end
+
+    ALL: Array[singleton(Arcp::Error)]
+    WIRE_CODES: Array[String]
+    BY_CODE: Hash[String, singleton(Arcp::Error)]
+    RETRYABLE_BY_DEFAULT: Array[String]
+    NON_RETRYABLE_BY_DEFAULT: Array[String]
+
+    def self.for: (String, ?message: String?, ?details: Hash[untyped, untyped]) -> Arcp::Error
+  end
+end

data/sig/arcp/job.rbs

@@ -0,0 +1,83 @@
+module Arcp
+  module Job
+    module EventKind
+      PROGRESS: String
+      RESULT_CHUNK: String
+      LOG: String
+      THOUGHT: String
+      TOOL_CALL: String
+      TOOL_RESULT: String
+      STATUS: String
+      METRIC: String
+      TRACE_SPAN: String
+      DELEGATE: String
+      ALL: Array[String]
+    end
+
+    class AgentRef
+      attr_reader name: String
+      attr_reader version: String?
+      def self.parse: (String?) -> AgentRef?
+      def to_s: () -> String
+    end
+
+    class Event
+      attr_reader kind: String
+      attr_reader body: untyped
+      def self.from_h: (Hash[String | Symbol, untyped]) -> Event
+      def to_h: () -> Hash[String, untyped]
+      def known?: () -> bool
+    end
+
+    class Handle
+      attr_reader job_id: String
+      attr_reader agent: String
+      attr_reader submitted_at: String?
+      attr_reader lease: Arcp::Lease::Lease?
+      attr_reader credentials: Array[Arcp::Credential]?
+      def subscribe: (client: Arcp::Client, **untyped) -> Enumerator[Event, void]
+      def cancel: (client: Arcp::Client, ?reason: String?) -> Envelope
+      def get_result: (client: Arcp::Client) -> Result
+      def credential_for: (endpoint: String) -> Arcp::Credential?
+    end
+
+    class Accepted
+      attr_reader job_id: String
+      attr_reader agent: String
+      attr_reader accepted_at: String?
+      attr_reader lease: Arcp::Lease::Lease?
+      attr_reader credentials: Array[Arcp::Credential]?
+      def self.from_h: (Hash[String | Symbol, untyped]) -> Accepted
+      def to_h: () -> Hash[String, untyped]
+    end
+
+    class Summary
+      attr_reader job_id: String
+      attr_reader agent: String
+      attr_reader status: String
+      attr_reader created_at: String?
+      attr_reader lease_expires_at: String?
+      attr_reader budget_remaining: Hash[String, String]?
+    end
+
+    class Result
+      attr_reader job_id: String
+      attr_reader final_status: String
+      attr_reader result: untyped
+      attr_reader result_id: String?
+      attr_reader result_size: Integer?
+      attr_reader completed_at: String?
+      def chunked?: () -> bool
+    end
+
+    class JobError
+      attr_reader job_id: String
+      attr_reader final_status: String
+      attr_reader code: String
+      attr_reader message: String?
+      attr_reader retryable: bool
+      attr_reader details: Hash[String, untyped]
+      def to_exception: () -> Arcp::Error
+    end
+  end
+end

data/sig/arcp/lease.rbs

@@ -0,0 +1,41 @@
+module Arcp
+  module Lease
+    class LeaseConstraints
+      attr_reader expires_at: String?
+      attr_reader max_budget: Hash[String, untyped]?
+      def self.from_h: (Hash[String | Symbol, untyped]?) -> LeaseConstraints?
+      def to_h: () -> Hash[String, untyped]
+      def validate!: () -> void
+    end
+
+    class CostBudget
+      attr_reader per_currency: Hash[String, BigDecimal]
+      def self.parse: (Array[String]) -> CostBudget
+      def to_a: () -> Array[String]
+      def to_h: () -> Hash[String, untyped]
+      def remaining: (String) -> BigDecimal
+      def currencies: () -> Array[String]
+    end
+
+    class LeaseRequest
+      attr_reader capabilities: Array[String]
+      attr_reader budget: CostBudget?
+      attr_reader model_use: Array[String]?
+      attr_reader expires_at: String?
+      def self.from_h: (Hash[String | Symbol, untyped]?) -> LeaseRequest?
+      def to_h: () -> Hash[String, untyped]
+    end
+
+    class Lease
+      attr_reader id: String
+      attr_reader capabilities: Array[String]
+      attr_reader budget: CostBudget?
+      attr_reader model_use: Array[String]?
+      attr_reader expires_at: String?
+      attr_reader issued_at: String
+      def self.from_h: (Hash[String | Symbol, untyped]) -> Lease
+      def to_h: () -> Hash[String, untyped]
+      def expired?: (Time) -> bool
+    end
+  end
+end

data/sig/arcp/runtime.rbs

@@ -0,0 +1,41 @@
+module Arcp
+  module Runtime
+    class Runtime
+      attr_reader auth_verifier: untyped
+      attr_reader name: String
+      attr_reader version: String
+      attr_reader heartbeat_interval_sec: Integer?
+      attr_reader resume_window_sec: Integer
+      attr_reader clock: untyped
+      attr_reader job_manager: JobManager
+      attr_reader lease_manager: LeaseManager
+      attr_reader subscription_manager: SubscriptionManager
+      attr_reader event_log: EventLog
+      attr_reader credential_registry: CredentialRegistry?
+      attr_reader enforce_model_use: bool
+
+      def initialize: (auth_verifier: untyped, ?name: String, ?version: String, ?heartbeat_interval_sec: Integer?, ?resume_window_sec: Integer, ?clock: untyped, ?credential_provisioner: Arcp::CredentialProvisioner?, ?credential_store: Arcp::Credentials::CredentialStore?, ?require_durable_store: bool, ?enforce_model_use: bool) -> void
+      def register_agent: (name: String, versions: Array[String], default: String, handler: ^(JobContext) -> void) -> void
+      def local_capabilities: (?agents_inventory: bool) -> Arcp::Session::CapabilitySet
+      def accept: (Arcp::Transport::Base) -> untyped
+      def shutdown: (?reason: String?) -> void
+    end
+
+    class JobManager end
+    class LeaseManager
+      def check_model!: (String, model_id: String) -> bool
+    end
+    class CredentialRegistry
+      def issue_for: (job_id: String, lease: Arcp::Lease::Lease?, agent: String, principal_id: String) -> Array[Arcp::Credential]
+      def rotate: (job_id: String, credential_id: String, new_value: String) -> String
+      def revoke_all: (job_id: String) -> Integer
+      def reconcile_on_startup!: () -> void
+    end
+    class SubscriptionManager end
+    class EventLog end
+    class JobContext
+      def rotate_credential: (id: String, new_value: String) -> untyped
+    end
+    class SessionActor end
+  end
+end

data/sig/arcp/serializer.rbs

@@ -0,0 +1,8 @@
+module Arcp
+  module Serializer
+    def self.backend: () -> Symbol
+    def self.backend=: (Symbol) -> Symbol
+    def self.dump: (untyped) -> String
+    def self.load: (String?) -> untyped
+  end
+end