mirrors-sdk 0.1.0

data/lib/mirrors_sdk/client.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "digest"
+require "monitor"
+
+module MirrorsSDK
+  # The application owns its model/tool loop; this client only captures and retrieves.
+  class Mirrors
+    def initialize(**options)
+      @pid, @lock = Process.pid, Monitor.new
+      @closed, @failed, @sequence = false, false, 0
+      @deliveries = Deliveries.new
+      @traces, @recent = {}, {}
+      begin
+        @config = Config.new(**options)
+      rescue StandardError
+        @config = nil
+      end
+      @enabled = !!(@config && @config.enabled)
+      begin
+        @worker = Worker.new(@config) if @config
+        @context = ContextHost.new(@config, @worker&.transport, @worker&.context_executor)
+        @worker&.start(@context)
+      rescue StandardError
+        @failed = true
+        @worker&.dispose
+        @context ||= ContextHost.new(nil, nil, nil)
+        @context.stop("worker_failed")
+      end
+    end
+
+    def capture_trace(trace, final: false, terminal: nil)
+      started = monotonic
+      return forked_ticket if forked?
+
+      reason = @lock.synchronize { unavailable }
+      return @deliveries.drop(reason) if reason
+
+      begin
+        snapshot = Wire.snapshot(trace, final: final, terminal: terminal)
+        encoded = Wire.encode(snapshot)
+        value = { "trace" => snapshot, "final" => final, "captureOnly" => true }
+        value["terminal"] = String.new(terminal) unless terminal.nil?
+        digest = Digest::SHA256.digest(Wire.encode(value))
+        metadata = source_metadata(snapshot)
+      rescue StandardError
+        identifier = trace_identifier(trace)
+        release_trace(identifier) if identifier
+        return @deliveries.drop("invalid_evidence")
+      end
+      @lock.synchronize do
+        reason = unavailable
+        return @deliveries.drop(reason) if reason
+
+        trace_id = snapshot["id"]
+        if @recent.key?(trace_id)
+          recent = @recent[trace_id]
+          return recent && recent[0] == digest ? recent[1] : @deliveries.drop("terminal_conflict")
+        end
+        previous = @traces[trace_id]
+        if previous && previous[2] != metadata
+          release_trace(trace_id) if final
+          return @deliveries.drop("invalid_evidence")
+        end
+        final ? @context.release(trace_id) : @context.observe(trace_id, encoded)
+        return previous[1] if previous && previous[0] == digest && previous[1].receipt.status == "pending"
+
+        if @deliveries.full?(final) || (!final && !previous && @traces.length >= 64)
+          release_trace(trace_id) if final
+          return @deliveries.drop("capacity")
+        end
+        ticket = @deliveries.create(final, trace_id)
+        if final
+          @traces.delete(trace_id)
+          remember(trace_id, [digest, ticket])
+        else
+          @traces[trace_id] = [digest, ticket, metadata]
+        end
+        budget = @config.timeout_ms || (final ? 6000 : 1000)
+        @sequence += 1
+        begin
+          job = @worker.capture(value, deadline: started + budget / 1000.0, sequence: @sequence)
+          if job
+            @deliveries.attach(ticket, job)
+            job.on_complete { |done| capture_done(ticket, done) }
+          else
+            @deliveries.settle(ticket, DeliveryReceipt.new("dropped", "capacity"))
+            @worker.release(trace_id) if final
+          end
+        rescue StandardError
+          @deliveries.settle(ticket, DeliveryReceipt.new("unconfirmed", "worker_failed"))
+          @worker.release(trace_id) if final
+        end
+        ticket
+      end
+    end
+
+    def get_context(trace, timeout_ms: 1000, cancel: nil)
+      started = monotonic
+      return ContextResult.new(reason: "forked_process") if forked?
+
+      @lock.synchronize do
+        reason = unavailable
+        reason ||= "invalid_options" unless cancel.nil? || cancel.instance_of?(Cancellation)
+        reason ||= "canceled" if cancel.instance_of?(Cancellation) && cancel.canceled?
+        reason ||= "execution_closed" if known_closed?(trace)
+        return @context.empty(reason, started) if reason
+      end
+      wait = @context.start(trace, timeout_ms: timeout_ms, started: started)
+      # Finalization can race with snapshot preparation outside the client lock.
+      @lock.synchronize { @context.release(trace_identifier(trace)) if known_closed?(trace) }
+      @context.await(wait, cancel: cancel)
+    end
+
+    def release_trace(trace_id)
+      return if forked?
+      begin
+        return unless Object.instance_method(:class).bind(trace_id).call == String
+
+        trace_id = String.new(trace_id)
+        Wire.id(trace_id)
+      rescue StandardError
+        return
+      end
+      @lock.synchronize do
+        @context.release(trace_id)
+        @traces.delete(trace_id)
+        remember(trace_id, nil) unless @recent.key?(trace_id)
+        @deliveries.cancel("canceled", trace_id)
+        @worker&.release(trace_id)
+      end
+      nil
+    end
+
+    def set_enabled(enabled)
+      return if forked? || !(enabled.equal?(true) || enabled.equal?(false))
+
+      @lock.synchronize do
+        return if @closed || @enabled == enabled
+
+        @enabled = enabled
+        @context.set_enabled(enabled)
+        unless enabled
+          @traces.keys.each { |trace_id| release_trace(trace_id) }
+          @deliveries.cancel("disabled")
+        end
+        @worker&.set_enabled(enabled)
+      end
+      nil
+    end
+
+    def flush(timeout_ms: 2000)
+      return FlushResult.new(unconfirmed: 1) if forked?
+
+      @deliveries.flush(timeout_ms)
+    end
+
+    def close(timeout_ms: 2000)
+      return FlushResult.new(unconfirmed: 1) if forked?
+
+      @lock.synchronize do
+        @closed = true
+        @context.stop
+      end
+      result = flush(timeout_ms: timeout_ms)
+      dispose
+      result
+    end
+
+    def dispose
+      return if forked?
+
+      @lock.synchronize do
+        @closed = true
+        @context.stop
+        @traces.clear
+        @recent.clear
+        @deliveries.cancel("closed")
+        @worker&.dispose
+      end
+      nil
+    end
+
+    def diagnostics
+      return { reason: "forked_process" } if forked?
+
+      @lock.synchronize do
+        @deliveries.diagnostics.merge(active_executions: @traces.length, recent_executions: @recent.length)
+      end
+    end
+
+    def start_turn
+      TurnTimer.new
+    end
+
+    def self.start_turn
+      TurnTimer.new
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def forked?
+      Process.pid != @pid
+    end
+
+    def unavailable
+      return "invalid_options" unless @config
+      return "worker_failed" if @failed
+      return "closed" if @closed
+      return "disabled" unless @enabled
+      return "worker_failed" unless @worker
+
+      nil
+    end
+
+    def known_closed?(trace)
+      identifier = trace_identifier(trace)
+      identifier && @recent.key?(identifier)
+    end
+
+    def trace_identifier(trace)
+      return unless Object.instance_method(:class).bind(trace).call == Hash
+
+      identifier = Hash.instance_method(:[]).bind(trace).call("id")
+      return unless Object.instance_method(:class).bind(identifier).call == String
+
+      Wire.id(String.new(identifier))
+    rescue StandardError
+      nil
+    end
+
+    def remember(trace_id, value)
+      @recent.delete(trace_id)
+      @recent[trace_id] = value
+      @recent.shift if @recent.length > 128
+    end
+
+    def source_metadata(trace)
+      %w[model entryPoint completeness conversationId conversationRevision].each_with_object({}) do |key, result|
+        result[key] = trace[key] if trace.key?(key)
+      end
+    end
+
+    def capture_done(ticket, job)
+      receipt = job.value
+      @deliveries.settle(ticket, receipt)
+    rescue StandardError
+      @deliveries.settle(ticket, DeliveryReceipt.new("unconfirmed", "transport"))
+    end
+
+    def forked_ticket
+      ticket = DeliveryTicket.new("forked")
+      ticket.__send__(:settle, DeliveryReceipt.new("dropped", "forked_process"))
+      ticket
+    end
+  end
+end

data/lib/mirrors_sdk/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module MirrorsSDK
+  # Immutable validated settings; credentials never appear in diagnostic inspection.
+  class Config
+    CLASS = Object.instance_method(:class)
+    attr_reader :api_url, :api_key, :agent_id, :timeout_ms, :enabled,
+                :failure_threshold, :cooldown_ms, :heartbeat_interval_ms, :mode_lease_ms
+
+    def initialize(api_url:, api_key:, agent_id:, timeout_ms: nil, enabled: true,
+                   failure_threshold: 3, cooldown_ms: 30_000,
+                   heartbeat_interval_ms: 1_000, mode_lease_ms: 3_000)
+      api_url = plain_string(api_url, "API URL")
+      api_key = plain_string(api_key, "API key")
+      agent_id = plain_string(agent_id, "agent ID")
+      unless api_url.bytesize.between?(1, 4096) &&
+             !api_url.match?(/[\x00-\x20\x7f\\?#]/)
+        raise ArgumentError, "Invalid API URL"
+      end
+      uri = URI.parse(api_url)
+      unless uri.hostname && !uri.hostname.empty? && !uri.userinfo &&
+             uri.port && uri.port.between?(1, 65_535) &&
+             (uri.scheme == "https" || (uri.scheme == "http" &&
+               %w[localhost 127.0.0.1 ::1].include?(uri.hostname)))
+        raise ArgumentError, "HTTPS is required except for loopback HTTP"
+      end
+      unless api_key.bytesize.between?(1, 4096) &&
+             !api_key.match?(/[^\x21-\x7e]/)
+        raise ArgumentError, "Invalid API key"
+      end
+      unless agent_id.match?(/\A[A-Za-z0-9_.-]{1,128}\z/)
+        raise ArgumentError, "Invalid agent ID"
+      end
+      raise ArgumentError, "enabled must be a boolean" unless true.equal?(enabled) || false.equal?(enabled)
+
+      integer(timeout_ms, 1, 30_000, "timeout_ms") unless nil.equal?(timeout_ms)
+      integer(failure_threshold, 1, 100, "failure_threshold")
+      integer(cooldown_ms, 1, 300_000, "cooldown_ms")
+      integer(heartbeat_interval_ms, 20, 1_000, "heartbeat_interval_ms")
+      integer(mode_lease_ms, 100, 3_000, "mode_lease_ms")
+      if heartbeat_interval_ms >= mode_lease_ms
+        raise ArgumentError, "Heartbeat interval must be shorter than the mode lease"
+      end
+
+      @api_url, @api_key, @agent_id = [api_url, api_key, agent_id].map(&:freeze)
+      @timeout_ms, @enabled = timeout_ms, enabled
+      @failure_threshold, @cooldown_ms = failure_threshold, cooldown_ms
+      @heartbeat_interval_ms, @mode_lease_ms = heartbeat_interval_ms, mode_lease_ms
+      freeze
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Invalid API URL"
+    end
+
+    def inspect
+      "#<MirrorsSDK::Config agent_id=#{@agent_id.inspect} enabled=#{@enabled}>"
+    end
+
+    private
+
+    def plain_string(value, name)
+      raise ArgumentError, "Invalid #{name}" unless CLASS.bind(value).call == String
+
+      String.new(value)
+    end
+
+    def integer(value, minimum, maximum, name)
+      unless CLASS.bind(value).call == Integer && value.between?(minimum, maximum)
+        raise ArgumentError, "Invalid #{name}"
+      end
+    end
+  end
+end

data/lib/mirrors_sdk/context.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "securerandom"
+require "timeout"
+
+module MirrorsSDK
+  # Keeps decisions bound to the evidence, mode lease and caller's original budget.
+  class ContextHost
+    OBJECT_CLASS = Object.instance_method(:class)
+    HASH_GET = Hash.instance_method(:[])
+    Wait = Struct.new(:identifier, :trace_id, :snapshot, :started, :deadline,
+                      :version, :shadow, :result, :rejection, :job, :condition,
+                      keyword_init: true)
+
+    def initialize(config, transport = nil, executor = nil)
+      @config, @transport, @executor = config, transport, executor
+      @lock = Monitor.new
+      @pending = {}
+      @mode = nil
+      @expires = 0.0
+      @enabled = !!(config && config.enabled)
+      @closed = false
+    end
+
+    def get(trace, timeout_ms: 1000, cancel: nil, started: now)
+      return empty("canceled", started) if canceled?(cancel)
+
+      self.await(start(trace, timeout_ms: timeout_ms, started: started), cancel: cancel)
+    end
+
+    # Two phases let the client fence finalization that races with snapshot copying.
+    def start(trace, timeout_ms: 1000, started: now)
+      wait = Wait.new(started: started, deadline: started, condition: @lock.new_cond)
+      unless timeout_ms.instance_of?(Integer) && timeout_ms.between?(1, 1000)
+        wait.result = empty("invalid_options", started)
+        return wait
+      end
+      wait.deadline += timeout_ms / 1000.0
+      @lock.synchronize do
+        reason = unavailable(wait.deadline)
+        if reason && reason != "shadow"
+          wait.result = empty(reason, started)
+          return wait
+        end
+        trace_id = HASH_GET.bind(trace).call("id") if OBJECT_CLASS.bind(trace).call == Hash
+        unless OBJECT_CLASS.bind(trace_id).call == String
+          wait.result = empty("invalid_evidence", started)
+          return wait
+        end
+        release(trace_id, "superseded")
+        if @pending.length >= 16
+          wait.result = empty("capacity", started)
+          return wait
+        end
+        wait.identifier = SecureRandom.uuid
+        wait.trace_id = String.new(trace_id)
+        wait.version = @mode["version"]
+        wait.shadow = reason == "shadow"
+        @pending[wait.identifier] = wait
+      end
+
+      # Reserve capacity before copying; never hold the shared lock during encoding.
+      begin
+        snapshot = Wire.snapshot(trace, deadline: wait.deadline)
+        encoded = Wire.encode(snapshot, deadline: wait.deadline)
+        request = { "protocol" => 1, "agentId" => @config.agent_id,
+                    "requestId" => wait.identifier, "trace" => snapshot }
+        request["shadowOnly"] = true if wait.shadow
+        body = Wire.encode(request, limit: 1_048_576, deadline: wait.deadline)
+      rescue StandardError => error
+        @lock.synchronize { finish(wait, error.is_a?(Timeout::Error) ? "timeout" : "invalid_evidence") }
+        return wait
+      end
+
+      @lock.synchronize do
+        return wait unless @pending[wait.identifier].equal?(wait)
+        if now >= wait.deadline
+          finish(wait, "timeout")
+          return wait
+        end
+        wait.snapshot = encoded
+        wait.result = empty("shadow", started) if wait.shadow
+        begin
+          wait.job = @executor.submit do |token|
+            @transport.request("retrieve-context", body, deadline: wait.deadline, cancel: token) do |value|
+              Wire.context_response(value, request)
+            end
+          end
+          if wait.job
+            wait.job.on_complete { |job| receive(wait, job) }
+          else
+            finish(wait, "capacity")
+          end
+        rescue StandardError
+          finish(wait, "worker_failed")
+        end
+      end
+      wait
+    end
+
+    def await(wait, cancel: nil)
+      completed = false
+      @lock.synchronize do
+        loop do
+          reason = canceled?(cancel) ? "canceled" : mode_reason
+          reason ||= "timeout" if now >= wait.deadline
+          finish(wait, reason) if !wait.result && reason
+          break if wait.result
+
+          wait.condition.wait([0.005, [wait.deadline - now, 0].max].min)
+        end
+        result = finalize(wait, cancel)
+        completed = true
+        result
+      end
+    ensure
+      @lock.synchronize { finish(wait, "canceled") } unless completed
+    end
+
+    def empty(reason, started)
+      @lock.synchronize do
+        fresh_mode = @mode && now < @expires && wall < Wire.utc(@mode["expiresAt"])
+        mode = fresh_mode ? @mode["mode"] : "shadow"
+        ContextResult.new(mode: reason == "disabled" ? "off" : mode,
+                          delivery: reason == "canceled" ? "canceled" : "unconfirmed",
+                          reason: reason, elapsed_ms: [0, (now - started) * 1000].max)
+      end
+    end
+
+    def observe_mode(value, started)
+      @lock.synchronize do
+        return if @closed || !@enabled || !@config
+        return unless (started.instance_of?(Integer) || started.instance_of?(Float)) &&
+                      started.finite? && started <= now
+        return unless Wire.mode_response(value, @config.agent_id)
+
+        changed = @mode && [@mode["version"], @mode["mode"]] != [value["version"], value["mode"]]
+        @mode = value.dup
+        @expires = [now + [0, Wire.utc(value["expiresAt"]) - wall].max,
+                    started + [Wire.lifetime(value), @config.mode_lease_ms / 1000.0].min].min
+        invalidate("mode_changed") if changed
+      end
+    end
+
+    def observe(trace_id, snapshot)
+      @lock.synchronize do
+        @pending.values.each do |wait|
+          finish(wait, "superseded") if wait.trace_id == trace_id && wait.snapshot != snapshot
+        end
+      end
+    end
+
+    def release(trace_id, reason = "execution_closed")
+      @lock.synchronize do
+        @pending.values.each { |wait| finish(wait, reason) if wait.trace_id == trace_id }
+      end
+    end
+
+    def set_enabled(enabled)
+      @lock.synchronize do
+        @enabled = enabled
+        @mode = nil
+        @expires = 0
+        invalidate("disabled") unless enabled
+      end
+    end
+
+    def stop(reason = "closed")
+      @lock.synchronize do
+        @closed = true
+        invalidate(reason)
+      end
+    end
+
+    def diagnostics
+      @lock.synchronize { { pending_context: @pending.length, mode: @mode && @mode["mode"] } }
+    end
+
+    private
+
+    def unavailable(deadline)
+      return "invalid_options" unless @config
+      return "closed" if @closed
+      return "disabled" unless @enabled
+      return "timeout" if now >= deadline
+      return "worker_failed" unless @transport && @executor
+
+      mode_reason
+    end
+
+    def mode_reason
+      return "mode_unknown" unless @mode
+      return "mode_expired" if now >= @expires || wall >= Wire.utc(@mode["expiresAt"])
+
+      @mode["mode"] unless @mode["mode"] == "active"
+    end
+
+    def receive(wait, job)
+      @lock.synchronize do
+        return unless @pending[wait.identifier].equal?(wait)
+        reason = mode_reason
+        if wait.shadow || reason
+          finish(wait, reason || "shadow")
+          return
+        end
+        begin
+          value = job.value
+          freshness = ContextFreshness.new(
+            request_id: value["requestId"], trace_id: value["traceId"],
+            decision_id: value["decisionId"], mode_version: value["modeVersion"],
+            issued_at: value["issuedAt"], expires_at: value["expiresAt"]
+          )
+          reason = freshness_reason(wait, freshness)
+          if reason
+            finish(wait, reason)
+          else
+            wait.result = ContextResult.new(context: value["context"] || "", mode: value["mode"],
+                                            delivery: "accepted", reason: value["reason"],
+                                            elapsed_ms: (now - wait.started) * 1000, freshness: freshness)
+            wait.condition.broadcast
+          end
+        rescue StandardError => error
+          finish(wait, error.respond_to?(:reason) ? error.reason : "transport")
+        end
+      end
+    end
+
+    def freshness_reason(wait, freshness)
+      return "timeout" if now >= wait.deadline
+      return "mode_changed" if @mode["version"] != wait.version || freshness.mode_version != wait.version
+
+      dates = { "issuedAt" => freshness.issued_at, "expiresAt" => freshness.expires_at }
+      if Wire.utc(freshness.expires_at) <= wall || now >= wait.started + Wire.lifetime(dates)
+        "expired"
+      end
+    end
+
+    def finalize(wait, cancel)
+      result = wait.result
+      reason = "canceled" if canceled?(cancel)
+      if result.delivery == "accepted"
+        reason ||= wait.rejection
+        reason ||= "superseded" unless @pending[wait.identifier].equal?(wait)
+        reason ||= mode_reason || freshness_reason(wait, result.freshness)
+        @pending.delete(wait.identifier)
+      end
+      if reason
+        finish(wait, reason)
+        return empty(reason, wait.started)
+      end
+      ContextResult.new(context: result.context, mode: result.mode, delivery: result.delivery,
+                        reason: result.reason, elapsed_ms: [0, (now - wait.started) * 1000].max,
+                        freshness: result.freshness)
+    end
+
+    def finish(wait, reason)
+      @pending.delete(wait.identifier)
+      wait.rejection ||= reason
+      wait.result ||= empty(reason, wait.started)
+      wait.condition.broadcast
+      wait.job.cancel(reason) if wait.job
+    end
+
+    def invalidate(reason)
+      @pending.values.each { |wait| finish(wait, reason) }
+    end
+
+    def canceled?(cancel)
+      OBJECT_CLASS.bind(cancel).call == Cancellation && cancel.canceled?
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def wall
+      Time.now.to_f
+    end
+  end
+end

data/lib/mirrors_sdk/delivery.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module MirrorsSDK
+  # Bounded bookkeeping. Flush observes only tickets pending when it starts.
+  class Deliveries
+    def initialize
+      @lock = Monitor.new
+      @pending = {}
+      @counts = { submitted: 0, accepted: 0, dropped: 0, unconfirmed: 0 }
+    end
+
+    def create(final = false, trace_id = "")
+      @lock.synchronize do
+        ticket = DeliveryTicket.new
+        @pending[ticket.id] = [ticket, final, trace_id, nil]
+        @counts[:submitted] += 1
+        ticket
+      end
+    end
+
+    def drop(reason)
+      ticket = create
+      settle(ticket, DeliveryReceipt.new("dropped", reason))
+      ticket
+    end
+
+    def full?(final)
+      @lock.synchronize { @pending.values.count { |item| item[1] == final } >= 16 }
+    end
+
+    def attach(ticket, job)
+      @lock.synchronize do
+        item = @pending[ticket.id]
+        item[3] = job if item
+      end
+    end
+
+    def settle(ticket, receipt)
+      @lock.synchronize do
+        return unless @pending.delete(ticket.id)
+
+        @counts[receipt.status.to_sym] += 1
+        ticket.__send__(:settle, receipt)
+      end
+    end
+
+    def cancel(reason, trace_id = nil)
+      jobs = @lock.synchronize do
+        selected = @pending.values.select { |item| trace_id.nil? || (item[2] == trace_id && !item[1]) }
+        selected.each do |ticket, _final, _identifier, job|
+          settle(ticket, DeliveryReceipt.new(job ? "unconfirmed" : "dropped", reason))
+        end
+        selected.map(&:last).compact
+      end
+      jobs.each { |job| job.cancel(reason) }
+    end
+
+    def flush(timeout_ms)
+      tickets = @lock.synchronize { @pending.values.map(&:first) }
+      valid = (timeout_ms.instance_of?(Integer) || timeout_ms.instance_of?(Float)) && timeout_ms.between?(0, 30_000)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + (valid ? timeout_ms / 1000.0 : 0)
+      tickets.each { |ticket| ticket.wait([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max) }
+      counts = { accepted: 0, dropped: 0, unconfirmed: 0, pending: 0 }
+      tickets.each { |ticket| counts[ticket.receipt.status.to_sym] += 1 }
+      FlushResult.new(**counts)
+    end
+
+    def diagnostics
+      @lock.synchronize { @counts.merge(pending: @pending.length) }
+    end
+  end
+end