mirrors-sdk 0.1.0

data/lib/mirrors_sdk/wire.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+require_relative "snapshot"
+require_relative "agent_context"
+
+module MirrorsSDK
+  # Canonical evidence and receipt bindings shared by capture, retrieval and heartbeat.
+  class Wire
+    MODES = %w[active shadow off].freeze
+    BASE64 = /\A(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?\z/.freeze
+
+    def self.encode(value, limit: 1_000_000, deadline: nil)
+      Snapshot.encode(value, limit: limit, deadline: deadline)
+    end
+
+    def self.id(value)
+      unless value.instance_of?(String) && value.match?(/\A[A-Za-z0-9_.-]{1,128}\z/)
+        raise ArgumentError, "Invalid Mirrors identifier"
+      end
+      value
+    end
+
+    def self.utc(value)
+      unless value.instance_of?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\z/)
+        raise ArgumentError, "Canonical UTC timestamp required"
+      end
+      parsed = Time.iso8601(value).utc
+      raise ArgumentError, "Invalid UTC date" unless parsed.iso8601(3) == value
+
+      parsed.to_f
+    end
+
+    def self.snapshot(trace, final: false, terminal: nil, deadline: nil)
+      Snapshot.check_deadline(deadline)
+      unless (true.equal?(final) || false.equal?(final)) &&
+             (nil.equal?(terminal) || (final && Snapshot::CLASS.bind(terminal).call == String &&
+               %w[completed failed canceled].include?(String.new(terminal))))
+        raise ArgumentError, "Invalid execution ending"
+      end
+      value = JSON.parse(encode(trace, deadline: deadline))
+      Snapshot.check_deadline(deadline)
+      fields(value, %w[id messages], %w[conversationId conversationRevision model entryPoint completeness user turnLatencyMs agentContext])
+      id(value["id"])
+      messages(value["messages"], deadline)
+      AgentContextWire.validate(value["agentContext"]) if value.key?("agentContext")
+      if value.key?("conversationId") || value.key?("conversationRevision")
+        id(value["conversationId"])
+        revision = value["conversationRevision"]
+        unless revision.instance_of?(Integer) && revision.between?(1, Snapshot::SAFE_INTEGER)
+          raise ArgumentError, "Conversation identity requires a positive safe integer revision"
+        end
+      end
+      { "model" => 200, "entryPoint" => 256 }.each do |field, limit|
+        text(value[field], limit) if value.key?(field)
+      end
+      completeness(value["completeness"]) if value.key?("completeness")
+      end_user(value["user"]) if value.key?("user")
+      if value.key?("turnLatencyMs")
+        latency = value["turnLatencyMs"]
+        unless final && [Integer, Float].include?(latency.class) && latency.finite? && latency >= 0
+          raise ArgumentError, "Turn latency requires a final snapshot and finite nonnegative value"
+        end
+      end
+      Snapshot.check_deadline(deadline)
+      value
+    end
+
+    def self.lifetime(value)
+      ((utc(value["expiresAt"]) - utc(value["issuedAt"])) * 1000).round / 1000.0
+    end
+
+    def self.mode_response(value, agent_id)
+      value.instance_of?(Hash) && value["protocol"].instance_of?(Integer) &&
+        value["protocol"] == 1 && value["agentId"] == agent_id && MODES.include?(value["mode"]) &&
+        !!id(value["version"]) && dates(value, 3)
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def self.context_response(value, request)
+      return false unless response_binding(value, request, 1) && echo(value, request, "shadowOnly") &&
+                          !!id(value["modeVersion"]) && !!text(value["reason"], 128) &&
+                          dates(value, 5) && value.key?("context")
+
+      context = value["context"]
+      context.nil? || (context.instance_of?(String) && context.bytesize <= 32_768 &&
+        value["mode"] == "active" && !request["shadowOnly"])
+    rescue ArgumentError, TypeError, KeyError
+      false
+    end
+
+    def self.trace_response(value, request)
+      return false unless response_binding(value, request, 3) &&
+                          %w[ordinal final terminal captureOnly].all? { |field| echo(value, request, field) } &&
+                          value.key?("context") && value.key?("ingestion")
+
+      utc(value["expiresAt"])
+      context = value["context"]
+      if !context.nil? && (!context.instance_of?(String) || context.bytesize > 32_768 ||
+                          value["mode"] != "active" || request["final"] || request["captureOnly"])
+        return false
+      end
+      ingestion = value["ingestion"]
+      return !request["final"] if ingestion.nil?
+      return false unless request["final"]
+
+      fields(ingestion, %w[status jobId])
+      (ingestion["status"] == "queued" && !!id(ingestion["jobId"])) ||
+        (ingestion["status"] == "unsupported_history" && ingestion["jobId"].nil?)
+    rescue ArgumentError, TypeError, KeyError
+      false
+    end
+
+    def self.fields(value, required, optional = [])
+      unless value.instance_of?(Hash) && (required - value.keys).empty? &&
+             (value.keys - required - optional).empty?
+        raise ArgumentError, "Invalid canonical fields"
+      end
+      value
+    end
+
+    def self.text(value, limit = nil)
+      unless value.instance_of?(String) && (!limit || AgentContextWire.length(value).between?(1, limit))
+        raise ArgumentError, "Invalid canonical text"
+      end
+      value
+    end
+
+    def self.messages(value, deadline)
+      unless value.instance_of?(Array) && value.length <= 10_000
+        raise ArgumentError, "Invalid message collection"
+      end
+      value.each do |message|
+        Snapshot.check_deadline(deadline)
+        fields(message, %w[role content], %w[metadata])
+        unless %w[system user assistant tool].include?(message["role"])
+          raise ArgumentError, "Invalid message role"
+        end
+        content = message["content"]
+        next if content.instance_of?(String)
+        unless content.instance_of?(Array) && content.length <= 1000
+          raise ArgumentError, "Invalid message content"
+        end
+        content.each do |item|
+          Snapshot.check_deadline(deadline)
+          block(item)
+        end
+      end
+    end
+
+    def self.block(value)
+      raise ArgumentError, "Invalid canonical block" unless value.instance_of?(Hash)
+
+      case value["type"]
+      when "text", "reasoning"
+        fields(value, %w[type text], %w[metadata])
+        text(value["text"])
+      when "tool-call", "tool-result"
+        call = value["type"] == "tool-call"
+        required = call ? %w[type callId name arguments] : %w[type callId name value error]
+        fields(value, required, call ? %w[metadata providerExecuted] : %w[metadata])
+        id(value["callId"])
+        text(value["name"], 128)
+        flag = call ? "providerExecuted" : "error"
+        if value.key?(flag) && value[flag] != true && value[flag] != false
+          raise ArgumentError, "Invalid tool flag"
+        end
+      when "media"
+        media(value)
+      else
+        raise ArgumentError, "Unsupported canonical block"
+      end
+    end
+
+    def self.media(value)
+      fields(value, %w[type kind source], %w[metadata mediaType filename])
+      raise ArgumentError, "Invalid media kind" unless %w[image file].include?(value["kind"])
+
+      source = fields(value["source"], %w[encoding value])
+      contents = text(source["value"])
+      if source["encoding"] == "url"
+        uri = URI.parse(contents)
+        unless %w[http https].include?(uri.scheme) && uri.hostname && !uri.hostname.empty?
+          raise ArgumentError, "Invalid media URL"
+        end
+      elsif source["encoding"] != "base64" || !contents.match?(BASE64)
+        raise ArgumentError, "Invalid media encoding"
+      end
+      %w[mediaType filename].each { |field| text(value[field]) if value.key?(field) }
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Invalid media URL"
+    end
+
+    def self.completeness(value)
+      fields(value, %w[history original_content ended])
+      unless %w[complete truncated].include?(value["history"]) &&
+             %w[complete partial].include?(value["original_content"]) &&
+             %w[completed abandoned unknown].include?(value["ended"])
+        raise ArgumentError, "Invalid source completeness"
+      end
+    end
+
+    def self.end_user(value)
+      fields(value, %w[id], %w[segment])
+      { "id" => 256, "segment" => 64 }.each do |field, limit|
+        next unless value.key?(field)
+
+        trimmed = text(value[field]).gsub(AgentContextWire::TRIM, "")
+        unless AgentContextWire.length(trimmed).between?(1, limit) && !trimmed.match?(/\p{Cc}/)
+          raise ArgumentError, "Invalid end user"
+        end
+        value[field] = trimmed
+      end
+    end
+
+    def self.dates(value, maximum)
+      duration = lifetime(value)
+      duration > 0 && duration <= maximum && utc(value["issuedAt"]) <= Time.now.to_f + 0.1
+    end
+
+    def self.echo(value, request, field)
+      value.key?(field) == request.key?(field) && value[field].class == request[field].class &&
+        value[field] == request[field]
+    end
+
+    def self.response_binding(value, request, protocol)
+      value.instance_of?(Hash) && value["protocol"].instance_of?(Integer) && value["protocol"] == protocol &&
+        value["agentId"] == request["agentId"] && value["traceId"] == request.fetch("trace").fetch("id") &&
+        value["requestId"] == request["requestId"] && value["role"] == "system" &&
+        MODES.include?(value["mode"]) && !!id(value["decisionId"])
+    end
+
+    private_class_method :fields, :text, :messages, :block, :media, :completeness,
+                         :end_user, :dates, :echo, :response_binding
+  end
+end

data/lib/mirrors_sdk/worker.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module MirrorsSDK
+  # Independent bounded pools keep optional capture traffic out of the context path.
+  class Worker
+    attr_reader :transport, :context_executor
+
+    def initialize(config)
+      @config, @lock = config, Monitor.new
+      @closed, @enabled, @generation = false, config.enabled, 0
+      @wake = @lock.new_cond
+      @transport = Transport.new(config)
+      @capture = CaptureRuntime.new(@transport, config)
+      @prefix = Executor.new(size: 2, capacity: 16, name: "mirrors-capture")
+      @final = Executor.new(size: 2, capacity: 16, name: "mirrors-final")
+      @context_executor = Executor.new(size: 2, capacity: 16, name: "mirrors-context")
+    rescue StandardError
+      dispose
+      raise
+    end
+
+    def start(context)
+      @heartbeat = Thread.new { heartbeat(context) }
+      @heartbeat.name = "mirrors-mode"
+      @heartbeat.report_on_exception = false
+    end
+
+    def capture(value, deadline:, sequence:)
+      @lock.synchronize do
+        return nil if @closed || !@enabled
+
+        runtime = @capture
+        pool = value["final"] ? @final : @prefix
+        pool.submit { |cancel| runtime.send(value, deadline: deadline, cancel: cancel, sequence: sequence) }
+      end
+    end
+
+    def release(trace_id)
+      @lock.synchronize { @capture.release(trace_id) }
+    end
+
+    def set_enabled(enabled)
+      @lock.synchronize do
+        return if @closed || @enabled == enabled
+
+        @enabled = enabled
+        @generation += 1
+        @heartbeat_cancel&.cancel("disabled")
+        @transport.set_enabled(enabled)
+        if enabled
+          @capture = CaptureRuntime.new(@transport, @config)
+        else
+          @capture.clear
+        end
+        @wake.broadcast
+      end
+    end
+
+    def dispose
+      @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        @heartbeat_cancel&.cancel("closed")
+        @capture&.clear
+        @transport&.close
+        [@prefix, @final, @context_executor].compact.each(&:shutdown)
+        @wake.broadcast
+      end
+    end
+
+    def diagnostics
+      { capture: @prefix.diagnostics, final: @final.diagnostics, context: @context_executor.diagnostics }
+    end
+
+    private
+
+    def heartbeat(context)
+      loop do
+        attempt = @lock.synchronize do
+          break if @closed
+
+          if @enabled
+            @heartbeat_cancel = Cancellation.new
+            [@generation, @heartbeat_cancel]
+          end
+        end
+        break if @closed
+
+        refresh(context, *attempt) if attempt
+        @lock.synchronize do
+          break if @closed
+
+          @wake.wait(@config.heartbeat_interval_ms / 1000.0 * (0.9 + rand * 0.2))
+        end
+      end
+    end
+
+    def refresh(context, generation, cancel)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      value = @transport.request("mode", nil, deadline: started + 0.75, cancel: cancel) do |response|
+        Wire.mode_response(response, @config.agent_id)
+      end
+      @lock.synchronize do
+        context.observe_mode(value, started) if @enabled && !@closed && @generation == generation
+      end
+    rescue StandardError
+      # A failed refresh never extends the previous lease.
+      nil
+    end
+  end
+end

data/lib/mirrors_sdk.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "mirrors_sdk/version"
+require_relative "mirrors_sdk/configuration"
+require_relative "mirrors_sdk/models"
+require_relative "mirrors_sdk/wire"
+require_relative "mirrors_sdk/executor"
+require_relative "mirrors_sdk/transport"
+require_relative "mirrors_sdk/delivery"
+require_relative "mirrors_sdk/capture"
+require_relative "mirrors_sdk/context"
+require_relative "mirrors_sdk/worker"
+require_relative "mirrors_sdk/client"

data/mirrors-sdk.gemspec

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "lib/mirrors_sdk/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mirrors-sdk"
+  spec.version = MirrorsSDK::VERSION
+  spec.authors = ["Mirrors"]
+  spec.summary = "Background trace capture and optional context for Ruby agents"
+  spec.description = "Capture canonical conversation history and retrieve bounded, " \
+                     "server-selected context while your application owns model calls and tools."
+  spec.homepage = "https://mirrors.dev/docs"
+  spec.required_ruby_version = ">= 3.3"
+  spec.files = Dir.chdir(__dir__) do
+    Dir["lib/**/*.rb", "test/**/*", "skills/**/*.md", "README.md", "Gemfile", "Rakefile", "mirrors-sdk.gemspec"]
+      .select { |path| File.file?(path) }.sort
+  end
+  spec.require_paths = ["lib"]
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/runmirrors/sidecar/tree/main/packages/ruby-sdk",
+    "documentation_uri" => "https://github.com/runmirrors/sidecar/blob/main/packages/ruby-sdk/README.md"
+  }
+end

data/skills/install-mirrors-ruby-sdk/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: install-mirrors-ruby-sdk
+description: Install or upgrade the Mirrors Ruby SDK and integrate original trace capture and optional context into an existing Ruby agent.
+---
+
+# Install Mirrors for Ruby
+
+Use `MirrorsSDK::Mirrors` from `require "mirrors_sdk"`. Preserve the application's
+prompt assembly, provider calls, tools, streams, errors and cancellation. Network
+workers, heartbeats, protocol handling and retries belong inside the SDK. Read the
+installed package's matching README before adapting existing hooks.
+
+## Select the package
+
+Use Ruby 3.3+ and the application's existing dependency manager. The gem is named
+`mirrors-sdk`; the require path is `mirrors_sdk`. Ruby, Python and npm package
+versions are independent.
+
+Verify that the intended official Mirrors release is published on the trusted gem
+registry before using a registry install. This source version does not establish
+RubyGems publication. Confirm ownership and source provenance, not merely a matching
+name. When available, add the verified stable version through the existing Gemfile
+and record its resolved version in the application's lockfile.
+
+If no official release exists, use an available reviewed checkout and record its
+revision. Replace this placeholder with the actual source directory:
+
+```ruby
+gem "mirrors-sdk", path: "/path/to/sidecar/packages/ruby-sdk", require: "mirrors_sdk"
+```
+
+Then run `bundle install` and verify:
+
+```sh
+bundle exec ruby -rmirrors_sdk -e 'puts MirrorsSDK::VERSION'
+```
+
+Respect constraints and lockfiles; explain conflicts instead of claiming an upgrade
+succeeded. Do not invent a release, substitute another package or publish the gem
+as part of installing it. The built gem includes this skill; find its directory via
+`Gem::Specification.find_by_name("mirrors-sdk").full_gem_path`.
+
+## Resolve the connection
+
+Reuse verified server configuration for `api_url`, `agent_id` and `api_key`. Resolve
+missing nonsecret settings from the intended agent's **Agent setup → SDK connection
+settings** in the signed-in dashboard. Use its API origin and generated agent ID
+together; never derive the ID from a display name or key. Load the matching agent's
+key with runtime read/write permissions from server secrets. Never print, commit or
+request a key in chat. Preserve explicit local, staging and self-hosted settings.
+
+Before real trace delivery, make one bounded, read-only
+`GET <api_url>/v1/agents/<agent_id>/runtime/mode` using `Authorization: Bearer ...`
+and `X-Mirrors-Protocol: 1`, refusing redirects. The response must identify the same
+agent. Shadow/off are valid modes. Recheck the environment, generated ID and key
+scope on 404. Do not upload customer history merely to test credentials.
+
+## Integrate the existing harness
+
+Create one reusable client per agent configuration in each worker **after forking**:
+
+```ruby
+require "mirrors_sdk"
+require "securerandom"
+
+mirrors = MirrorsSDK::Mirrors.new(
+  api_url: ENV.fetch("MIRRORS_API_URL"),
+  api_key: ENV.fetch("MIRRORS_API_KEY"),
+  agent_id: ENV.fetch("MIRRORS_AGENT_ID")
+)
+```
+
+Find the original-history logger, user-turn prompt assembly and existing execution
+ending hooks. Preserve complete original canonical messages, roles, reasoning,
+block order and tool associations. Use builtin JSON values and string-key hashes;
+canonical names remain camelCase (`conversationId`, `callId`, `turnLatencyMs`).
+Exclude Mirrors-added context, and never invent associations or truncate evidence.
+
+At user-message acceptance, create a fresh execution ID and optional turn timer.
+Keep them through the full model/tool loop and every retry:
+
+```ruby
+turn = mirrors.start_turn
+trace = { "id" => SecureRandom.uuid, "messages" => full_original_history }
+mirrors.capture_trace(trace)
+selected = mirrors.get_context(trace, timeout_ms: 1000, cancel: cancellation)
+# Preserve the host's cancellation check here before calling its provider.
+system = selected.context.empty? ? base_system : "#{base_system}\n\n#{selected.context}"
+response = existing_model_call(system: system, messages: original_messages)
+```
+
+The fragment's history, prompt, model and cancellation variables belong to the
+application. `cancellation` can be a `MirrorsSDK::Cancellation` token; call `cancel`
+at the host's cancellation hook and check `canceled?` before its provider call.
+Do not turn a canceled operation into a provider invocation.
+
+`get_context` returns an object with attributes. It synchronously waits within one
+total budget of at most 1,000 ms from entry; use a shorter `timeout_ms` to reduce
+waiting. It does not wait for capture. Event-loop applications should use their
+existing background execution facility. Empty context leaves the prompt unchanged.
+Use returned text promptly for that request, check `freshness.expires_at` if delayed,
+and retrieve again when history changes.
+
+Capture updated original snapshots at the logger without awaiting delivery. Only
+after the entire response stream, tools and retries finish, finalize once through
+the existing completion/failure/cancellation hook:
+
+```ruby
+ticket = mirrors.capture_trace(
+  trace.merge("messages" => completed_original_history, "turnLatencyMs" => turn.finish),
+  final: true,
+  terminal: "completed" # Use "failed" or "canceled" at those hooks.
+)
+```
+
+Terminal status describes execution ending, not task success. Put latency only on
+final capture, measure the whole turn and exclude capture delivery. Omit unknown
+duration. With no final evidence, `release_trace(trace["id"])` only cleans up local
+state. Never reuse execution IDs after completion, release, restart or disable.
+
+Continuing chats supply both `conversationId` and `conversationRevision` or neither.
+Allocate a positive safe-integer revision atomically in durable storage per
+execution, persist the pair and keep it fixed across snapshots/retries. Timestamps,
+message counts and process counters are invalid. Branches need distinct chat IDs.
+Optional `user` contains an opaque internal `id` and optional cohort `segment`.
+
+## Optional original instructions
+
+When the installed SDK and deployed API/worker readers support it, supply original
+instructions on `trace["agentContext"]`: `systemPrompt` and/or `skills`, where each
+skill has `name` and `content`. Read the application's prompt before adding Mirrors
+context; do not load arbitrary files or skills automatically. Include the object on
+the final snapshot: previous values are never inherited. Omit unknown fields; empty
+prompt/skills explicitly mean empty. Respect the installed README's character,
+count and byte limits. Preserve existing system messages without synthesizing copies.
+
+## Verify and shut down
+
+Inspect `ticket.receipt` outside the model path; `ticket.wait(2)` waits up to two
+seconds. Other timeout arguments use milliseconds. Accepted ingestion `queued`
+does not mean analysis completed; an unconfirmed write may have committed.
+
+At shutdown, stop admitting turns, let active turns finish and call
+`mirrors.close(timeout_ms: 2000)`. `flush` covers only tickets pending at entry;
+inspect accepted/dropped/unconfirmed/pending counts. Background work is best effort
+and no durable queue exists.
+
+Verify locally before real delivery: active context appends to a copied prompt;
+original evidence remains unchanged; empty/shadow/off/error/cancellation paths
+preserve host behavior; tools and streams finalize only at their true ending;
+shutdown is bounded. Report the installed version and observed receipt outcomes,
+distinguishing local tests from publication, hosted acceptance and model quality.