arcp 1.0.0

data/lib/arcp/job/subscribe.rb

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

data/lib/arcp/job/subscribed.rb

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

data/lib/arcp/job/summary.rb

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

data/lib/arcp/job/unsubscribe.rb

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

data/lib/arcp/job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'lease'
+require_relative 'job/agent_ref'
+require_relative 'job/submit'
+require_relative 'job/accepted'
+require_relative 'job/event'
+require_relative 'job/result'
+require_relative 'job/job_error'
+require_relative 'job/cancel'
+require_relative 'job/subscribe'
+require_relative 'job/subscribed'
+require_relative 'job/unsubscribe'
+require_relative 'job/handle'
+require_relative 'job/summary'

data/lib/arcp/lease.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'time'
+
+require_relative 'errors'
+require_relative 'credential'
+
+module Arcp
+  module Lease
+    LeaseConstraints = Data.define(:expires_at, :max_budget) do
+      def self.from_h(h)
+        return nil if h.nil?
+
+        h = h.transform_keys(&:to_s)
+        new(expires_at: h['expires_at'], max_budget: h['max_budget'])
+      end
+
+      def to_h
+        out = {}
+        out['expires_at'] = expires_at if expires_at
+        out['max_budget'] = max_budget if max_budget
+        out
+      end
+
+      def validate!
+        return if expires_at.nil?
+
+        t = Time.iso8601(expires_at)
+        raise Arcp::Errors::InvalidRequest, "expires_at must be UTC (use 'Z'): #{expires_at}" unless t.utc?
+      end
+    end
+
+    CostBudget = Data.define(:per_currency) do
+      def self.parse(entries)
+        h = {}
+        Array(entries).each do |entry|
+          ccy, amount = entry.to_s.split(':', 2)
+          if ccy.nil? || amount.nil?
+            raise Arcp::Errors::InvalidRequest,
+                  "malformed budget entry: #{entry.inspect}"
+          end
+
+          h[ccy] = BigDecimal(amount)
+        end
+        new(per_currency: h.freeze)
+      end
+
+      def to_a = per_currency.map { |ccy, amt| "#{ccy}:#{amt.to_s('F')}" }
+      def to_h = { 'cost.budget' => to_a }
+
+      def remaining(currency) = per_currency[currency] || BigDecimal('0')
+      def currencies = per_currency.keys
+    end
+
+    class BudgetCounter
+      attr_reader :remaining
+
+      def initialize(initial:)
+        @remaining = initial.dup
+      end
+
+      def try_decrement(currency, amount)
+        balance = @remaining[currency]
+        return false if balance.nil?
+        return false if balance < amount
+
+        @remaining[currency] = balance - amount
+        true
+      end
+
+      def get(currency) = @remaining[currency] || BigDecimal('0')
+      def negative?(currency) = (@remaining[currency] || BigDecimal('0')).negative?
+
+      def snapshot
+        @remaining.transform_values(&:dup).freeze
+      end
+    end
+
+    LeaseRequest = Data.define(:capabilities, :budget, :model_use, :expires_at) do
+      def initialize(capabilities:, budget: nil, model_use: nil, expires_at: nil)
+        super(
+          capabilities: Array(capabilities).freeze,
+          budget: budget,
+          model_use: model_use ? Array(model_use).freeze : nil,
+          expires_at: expires_at
+        )
+      end
+
+      def self.from_h(h)
+        return nil if h.nil?
+
+        h = h.transform_keys(&:to_s)
+        new(
+          capabilities: Array(h['capabilities']).freeze,
+          budget: h['cost.budget'] ? CostBudget.parse(h['cost.budget']) : nil,
+          model_use: h['model.use'] ? Array(h['model.use']).freeze : nil,
+          expires_at: h['expires_at']
+        )
+      end
+
+      def to_h
+        out = { 'capabilities' => capabilities }
+        out['cost.budget'] = budget.to_a if budget
+        out['model.use'] = model_use if model_use
+        out['expires_at'] = expires_at if expires_at
+        out
+      end
+    end
+
+    Lease = Data.define(:id, :capabilities, :budget, :model_use, :expires_at, :issued_at) do
+      def initialize(id:, capabilities:, issued_at:, budget: nil, model_use: nil, expires_at: nil)
+        super(
+          id: id,
+          capabilities: Array(capabilities).freeze,
+          budget: budget,
+          model_use: model_use ? Array(model_use).freeze : nil,
+          expires_at: expires_at,
+          issued_at: issued_at
+        )
+      end
+
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          id: h.fetch('id'),
+          capabilities: Array(h['capabilities']).freeze,
+          budget: h['cost.budget'] ? CostBudget.parse(h['cost.budget']) : nil,
+          model_use: h['model.use'] ? Array(h['model.use']).freeze : nil,
+          expires_at: h['expires_at'],
+          issued_at: h['issued_at']
+        )
+      end
+
+      def to_h
+        out = { 'id' => id, 'capabilities' => capabilities, 'issued_at' => issued_at }
+        out['cost.budget'] = budget.to_a if budget
+        out['model.use'] = model_use if model_use
+        out['expires_at'] = expires_at if expires_at
+        out
+      end
+
+      def expired?(now)
+        return false if expires_at.nil?
+
+        Time.iso8601(expires_at) <= now
+      end
+    end
+
+    module Subsetting
+      module_function
+
+      # Compute a delegate lease bounded by the parent. Raises
+      # `LeaseSubsetViolation` if requested capabilities exceed parent,
+      # requested expires_at is beyond parent, or remaining budget can't
+      # cover the requested amount.
+      def bound(parent:, request:, parent_remaining: nil)
+        excess = request.capabilities - parent.capabilities
+        unless excess.empty?
+          raise Arcp::Errors::LeaseSubsetViolation,
+                "child lease capabilities not in parent: #{excess.inspect}"
+        end
+
+        if request.expires_at && parent.expires_at
+          parent_t = Time.iso8601(parent.expires_at)
+          req_t = Time.iso8601(request.expires_at)
+          if req_t > parent_t
+            raise Arcp::Errors::LeaseSubsetViolation,
+                  "child expires_at #{request.expires_at} exceeds parent #{parent.expires_at}"
+          end
+        end
+
+        budget = nil
+        if request.budget
+          parent_pc = parent_remaining || (parent.budget&.per_currency || {})
+          missing = request.budget.per_currency.filter_map do |ccy, amt|
+            available = parent_pc[ccy] || BigDecimal('0')
+            (ccy if amt > available)
+          end
+          unless missing.empty?
+            raise Arcp::Errors::LeaseSubsetViolation,
+                  "child budget exceeds parent remaining for: #{missing.inspect}"
+          end
+
+          budget = request.budget
+        end
+
+        model_use = bound_model_use(parent: parent, request: request)
+
+        Lease.new(
+          id: Arcp::Ids.session_id.sub(/^ses_/, 'lse_'),
+          capabilities: request.capabilities,
+          budget: budget,
+          model_use: model_use,
+          expires_at: request.expires_at || parent.expires_at,
+          issued_at: Time.now.utc.iso8601
+        )
+      end
+
+      def bound_model_use(parent:, request:)
+        return nil unless request.model_use
+
+        unless request.model_use.all? { |pattern| Arcp::ModelPattern.implied_by?(parent.model_use, pattern) }
+          raise Arcp::Errors::LeaseSubsetViolation,
+                "child model.use expands beyond parent: #{request.model_use.inspect}"
+        end
+
+        request.model_use
+      end
+    end
+  end
+end

data/lib/arcp/message_types.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Arcp
+  module MessageTypes
+    SESSION_HELLO     = 'session.hello'
+    SESSION_WELCOME   = 'session.welcome'
+    SESSION_BYE       = 'session.bye'
+    SESSION_ERROR     = 'session.error'
+    SESSION_PING      = 'session.ping'
+    SESSION_PONG      = 'session.pong'
+    SESSION_ACK       = 'session.ack'
+    SESSION_LIST_JOBS = 'session.list_jobs'
+    SESSION_JOBS      = 'session.jobs'
+
+    JOB_SUBMIT        = 'job.submit'
+    JOB_ACCEPTED      = 'job.accepted'
+    JOB_EVENT         = 'job.event'
+    JOB_RESULT        = 'job.result'
+    JOB_ERROR         = 'job.error'
+    JOB_CANCEL        = 'job.cancel'
+    JOB_SUBSCRIBE     = 'job.subscribe'
+    JOB_SUBSCRIBED    = 'job.subscribed'
+    JOB_UNSUBSCRIBE   = 'job.unsubscribe'
+
+    ALL = [
+      SESSION_HELLO, SESSION_WELCOME, SESSION_BYE, SESSION_ERROR,
+      SESSION_PING, SESSION_PONG, SESSION_ACK,
+      SESSION_LIST_JOBS, SESSION_JOBS,
+      JOB_SUBMIT, JOB_ACCEPTED, JOB_EVENT, JOB_RESULT, JOB_ERROR,
+      JOB_CANCEL, JOB_SUBSCRIBE, JOB_SUBSCRIBED, JOB_UNSUBSCRIBE
+    ].freeze
+
+    def self.known?(type) = ALL.include?(type)
+  end
+end

data/lib/arcp/runtime/credential_registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../clock'
+require_relative '../credential'
+require_relative '../credential_provisioner'
+
+module Arcp
+  module Runtime
+    class CredentialRegistry
+      def initialize(provisioner:, store:, clock: Arcp::SystemClock.new)
+        @provisioner = provisioner
+        @store = store
+        @clock = clock
+        @mutex = Mutex.new
+      end
+
+      def issue_for(job_id:, lease:, agent:, principal_id:)
+        credentials = @provisioner.issue(
+          lease: lease, job_id: job_id, agent: agent, principal_id: principal_id
+        )
+        Array(credentials).each do |credential|
+          @store.record(job_id: job_id, credential_id: credential.id)
+        end
+        Array(credentials).freeze
+      end
+
+      def rotate(job_id:, credential_id:, new_value:)
+        revoke(credential_id)
+        new_id = "#{credential_id}_rotated_#{@clock.now.to_i}"
+        @store.record(job_id: job_id, credential_id: new_id)
+        new_id
+      end
+
+      def revoke_all(job_id:)
+        @store.outstanding(job_id: job_id).count do |credential_id|
+          revoke(credential_id).tap do |revoked|
+            @store.forget(job_id: job_id, credential_id: credential_id) if revoked
+          end
+        end
+      end
+
+      def reconcile_on_startup!
+        @store.all_outstanding.each do |job_id, credential_ids|
+          credential_ids.each do |credential_id|
+            @store.forget(job_id: job_id, credential_id: credential_id) if revoke(credential_id)
+          end
+        end
+        nil
+      end
+
+      private
+
+      def revoke(credential_id)
+        attempts = 0
+        begin
+          attempts += 1
+          @provisioner.revoke(credential_id: credential_id)
+          true
+        rescue StandardError
+          retry if attempts < 2
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/arcp/runtime/event_log.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Arcp
+  module Runtime
+    # In-memory ring of buffered events keyed by session_id. The runtime
+    # uses this for the resume window and `session.ack`-driven early
+    # eviction. A SQLite-backed variant (same API) is suitable for
+    # multi-process runtimes; for v1 we ship the in-memory implementation
+    # used by tests and the Falcon-hosted single-process runtime.
+    class EventLog
+      def initialize(window_sec: 300, clock: Arcp::SystemClock.new)
+        @window_sec = window_sec
+        @clock = clock
+        @sessions = Hash.new { |h, k| h[k] = [] }
+        @floor = Hash.new(0)
+        @mutex = Mutex.new
+      end
+
+      def append(session_id, envelope)
+        @mutex.synchronize do
+          @sessions[session_id] << [envelope, @clock.monotonic]
+        end
+        envelope
+      end
+
+      def floor(session_id) = @floor[session_id]
+
+      def evict_up_to(session_id, seq)
+        @mutex.synchronize do
+          @floor[session_id] = [@floor[session_id], seq].max
+          @sessions[session_id].reject! do |env, _t|
+            env.event_seq && env.event_seq <= seq
+          end
+        end
+      end
+
+      def replay(session_id, from_event_seq: nil)
+        @mutex.synchronize do
+          @sessions[session_id].each_with_object([]) do |(env, _t), out|
+            next if env.event_seq.nil?
+            next if from_event_seq && env.event_seq < from_event_seq
+
+            out << env
+          end
+        end
+      end
+
+      # Evict events past the resume window (advisory; consumer drives via timer).
+      def expire!
+        now = @clock.monotonic
+        @mutex.synchronize do
+          @sessions.each_value do |buf|
+            buf.reject! { |(_e, t)| (now - t) > @window_sec }
+          end
+        end
+      end
+
+      # @api private
+      def buffer_size(session_id) = @sessions[session_id].size
+    end
+  end
+end

data/lib/arcp/runtime/job_context.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'async/queue'
+require 'base64'
+require 'time'
+
+module Arcp
+  module Runtime
+    # Passed to an agent handler. Exposes emission seams (events,
+    # progress, tool calls, streamed result) and read-only state
+    # (job_id, agent, input, lease).
+    class JobContext
+      attr_reader :job_id, :agent, :input, :lease, :event_seq
+
+      def initialize(job_id:, agent:, input:, lease:, sink:)
+        @job_id = job_id
+        @agent = agent
+        @input = input
+        @lease = lease
+        @sink = sink
+        @event_seq = 0
+        @result_id = nil
+        @result_buffer = []
+        @done = false
+        @chunked = false
+        @mutex = Mutex.new
+      end
+
+      def emit(kind:, body:)
+        event = Arcp::Job::Event.new(kind: kind, body: body)
+        @event_seq = @sink.publish_event(@job_id, event)
+        event
+      end
+
+      def log(level:, message:, **fields)
+        emit(kind: Arcp::Job::EventKind::LOG,
+             body: Arcp::Job::EventBody::Log.new(level: level, message: message, fields: fields))
+      end
+
+      def progress(current:, total: nil, units: nil, message: nil)
+        emit(kind: Arcp::Job::EventKind::PROGRESS,
+             body: Arcp::Job::EventBody::Progress.new(current: current, total: total, units: units,
+                                                      message: message))
+      end
+
+      def metric(name:, value:, unit: nil)
+        emit(kind: Arcp::Job::EventKind::METRIC,
+             body: Arcp::Job::EventBody::Metric.new(name: name, value: value, unit: unit))
+      end
+
+      def status(phase:, message: nil, fields: {})
+        emit(kind: Arcp::Job::EventKind::STATUS,
+             body: Arcp::Job::EventBody::Status.new(phase: phase, message: message,
+                                                    fields: fields))
+      end
+
+      def rotate_credential(id:, new_value:)
+        new_id = @sink.runtime.credential_registry&.rotate(
+          job_id: job_id,
+          credential_id: id,
+          new_value: new_value
+        )
+        status(
+          phase: 'credential_rotated',
+          fields: { 'id' => new_id || id, 'value' => new_value }
+        )
+      end
+
+      def tool_call(call_id:, tool:, args:)
+        emit(kind: Arcp::Job::EventKind::TOOL_CALL,
+             body: Arcp::Job::EventBody::ToolCall.new(call_id: call_id, tool: tool, args: args))
+      end
+
+      def tool_result(call_id:, result: nil, error: nil)
+        emit(kind: Arcp::Job::EventKind::TOOL_RESULT,
+             body: Arcp::Job::EventBody::ToolResult.new(call_id: call_id, result: result, error: error))
+      end
+
+      def stream_result(encoding: 'utf8', &block)
+        raise Arcp::Errors::ProtocolViolation, 'result already finalized' if @done
+
+        @chunked = true
+        @result_id = Arcp::Ids.result_id
+
+        writer = ChunkWriter.new(ctx: self, encoding: encoding, result_id: @result_id)
+        if block
+          yield writer
+          writer.close
+          @result_buffer = writer.totals
+          @result_buffer
+        else
+          writer
+        end
+      end
+
+      def finish(result: nil)
+        raise Arcp::Errors::ProtocolViolation, 'result already finalized' if @done
+
+        if @chunked && !result.nil?
+          raise Arcp::Errors::ProtocolViolation, 'cannot mix inline result with result_chunk stream'
+        end
+
+        @done = true
+
+        @sink.publish_result(
+          @job_id,
+          Arcp::Job::Result.new(
+            job_id: @job_id, final_status: 'success',
+            result: result,
+            result_id: @chunked ? @result_id : nil,
+            result_size: @chunked ? @result_buffer[:bytes] : nil,
+            completed_at: Time.now.utc.iso8601
+          )
+        )
+      end
+
+      def fail!(code:, message: nil, retryable: false, details: {})
+        raise Arcp::Errors::ProtocolViolation, 'result already finalized' if @done
+
+        @done = true
+        @sink.publish_error(
+          @job_id,
+          Arcp::Job::JobError.new(
+            job_id: @job_id, final_status: 'error',
+            code: code, message: message, retryable: retryable, details: details
+          )
+        )
+      end
+
+      # @api private
+      class ChunkWriter
+        def initialize(ctx:, encoding:, result_id:)
+          @ctx = ctx
+          @encoding = encoding
+          @result_id = result_id
+          @seq = 0
+          @bytes = 0
+          @closed = false
+        end
+
+        def write(chunk, more: true)
+          raise Arcp::Errors::ProtocolViolation, 'stream closed' if @closed
+
+          data = case @encoding
+                 when 'base64' then Base64.strict_encode64(chunk)
+                 else chunk.dup.force_encoding('UTF-8')
+                 end
+          @bytes += chunk.bytesize
+          body = Arcp::Job::EventBody::ResultChunk.new(
+            result_id: @result_id, chunk_seq: @seq, data: data,
+            encoding: @encoding, more: more
+          )
+          @ctx.emit(kind: Arcp::Job::EventKind::RESULT_CHUNK, body: body)
+          @seq += 1
+        end
+
+        def close
+          return if @closed
+
+          @closed = true
+        end
+
+        def totals = { bytes: @bytes, chunks: @seq, result_id: @result_id }
+      end
+    end
+  end
+end