mirrors-sdk 0.1.0

data/test/transport_test.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "socket"
+require "stringio"
+require_relative "../lib/mirrors_sdk/configuration"
+require_relative "../lib/mirrors_sdk/transport"
+
+class TransportTest < Minitest::Test
+  def setup
+    @requests = Queue.new
+    @connections, @handlers = [], []
+    @behavior = ->(socket, _request) { respond(socket) }
+    @server = TCPServer.new("127.0.0.1", 0)
+    @config = MirrorsSDK::Config.new(api_url: "http://127.0.0.1:#{@server.addr[1]}/prefix",
+                                     api_key: "private-token", agent_id: "agent", failure_threshold: 1)
+    @transport = MirrorsSDK::Transport.new(@config)
+    @acceptor = Thread.new do
+      loop do
+        socket = @server.accept
+        @connections << socket
+        @handlers << Thread.new(socket) { |connection| handle(connection) }
+      end
+    rescue IOError, Errno::EBADF
+      nil
+    end
+  end
+
+  def teardown
+    @transport.close if @transport
+    @server.close if @server
+    @connections.each { |socket| socket.close unless socket.closed? }
+    @acceptor.join(0.2) if @acceptor
+    @handlers.each { |thread| thread.join(0.2) || thread.kill }
+  end
+
+  def test_exact_wire_binding_and_mode_get
+    body = '{"final":false,"text":"original"}'
+    assert_equal({ "ok" => true }, post(body))
+    request = @requests.pop
+    assert_equal "POST /prefix/v1/agents/agent/runtime/trace HTTP/1.1", request[:line]
+    assert_equal body, request[:body]
+    assert_equal "Bearer private-token", request[:headers]["authorization"]
+    assert_equal "3", request[:headers]["x-mirrors-protocol"]
+    assert_equal Digest::SHA256.hexdigest("trace\n#{body}"), request[:headers]["idempotency-key"]
+    @transport.request("mode", nil, deadline: monotonic + 1) { true }
+    request = @requests.pop
+    assert request[:line].start_with?("GET ")
+    assert_equal "", request[:body]
+    assert_equal "1", request[:headers]["x-mirrors-protocol"]
+  end
+
+  def test_total_deadline_bounds_trickling_response
+    @behavior = lambda do |socket, _request|
+      socket.write("HTTP/1.1 200 OK\r\nContent-Length: 1000\r\nConnection: close\r\n\r\n")
+      1000.times { socket.write(" "); sleep 0.005 }
+    end
+    started = monotonic
+    error = assert_raises(MirrorsSDK::TransportError) { post(timeout: 0.05) }
+    assert_equal "timeout", error.reason
+    assert_operator monotonic - started, :<, 0.3
+  end
+
+  def test_redirect_does_not_forward_credentials
+    @behavior = ->(socket, _) { respond(socket, status: 302, headers: "Location: /credential-target\r\n") }
+    assert_raises(MirrorsSDK::TransportError) { post }
+    assert_equal 1, @requests.size
+  end
+
+  def test_raw_and_decompressed_limits_and_valid_gzip
+    data = '{"data":"' + ("x" * 70_000) + '"}'
+    [nil, "gzip", "deflate"].each do |encoding|
+      reset_transport
+      payload = encode(data, encoding)
+      headers = encoding ? "Content-Encoding: #{encoding}\r\n" : ""
+      @behavior = ->(socket, _) { respond(socket, body: payload, headers: headers) }
+      error = assert_raises(MirrorsSDK::TransportError) { post }
+      assert_equal "response_too_large", error.reason
+    end
+    reset_transport
+    payload = encode('{"ok":true}', "gzip")
+    @behavior = ->(socket, _) { respond(socket, body: payload, headers: "Content-Encoding: gzip\r\n") }
+    assert_equal({ "ok" => true }, post)
+  end
+
+  def test_cancellation_releases_socket_without_opening_circuit
+    entered = Queue.new
+    @behavior = ->(socket, _) { entered << true; socket.read }
+    token = MirrorsSDK::Cancellation.new
+    job = Thread.new do
+      post(cancel: token)
+    rescue MirrorsSDK::TransportError => error
+      error
+    end
+    entered.pop
+    token.cancel
+    assert job.join(0.5), "Cancellation must interrupt a connected request"
+    assert_equal "canceled", job.value.reason
+    @behavior = ->(socket, _) { respond(socket) }
+    assert_equal({ "ok" => true }, post)
+  ensure
+    job.kill if job && job.alive?
+  end
+
+  def test_final_circuit_reconciles_exact_prefix_independently
+    body = '{"final":false,"requestId":"immutable-prefix"}'
+    @behavior = ->(socket, _) { respond(socket, status: 503) }
+    assert_raises(MirrorsSDK::TransportError) { post(body) }
+    first = @requests.pop
+    @behavior = ->(socket, _) { respond(socket) }
+    value = @transport.request("trace", body, deadline: monotonic + 1, final_recovery: true) { |v| v["ok"] }
+    assert_equal({ "ok" => true }, value)
+    second = @requests.pop
+    assert_equal first[:body], second[:body]
+    assert_equal first[:headers]["idempotency-key"], second[:headers]["idempotency-key"]
+    assert_equal "circuit_open", assert_raises(MirrorsSDK::TransportError) { post }.reason
+    assert_equal({ "ok" => true }, post('{"final":true}'))
+  end
+
+  def test_invalid_json_and_bindings_fail_closed
+    ['{"ok":true,"ok":false}', '{"value":NaN}', '{"ok":false}', "\xff".b].each do |body|
+      reset_transport
+      @behavior = ->(socket, _) { respond(socket, body: body) }
+      error = assert_raises(MirrorsSDK::TransportError) { post }
+      assert_equal "invalid_response", error.reason
+      assert_nil error.cause
+    end
+  end
+
+  def test_permanent_rejection_has_sanitized_message
+    @behavior = ->(socket, _) { respond(socket, status: 400, body: "private-token original history") }
+    error = assert_raises(MirrorsSDK::TransportError) { post }
+    assert error.permanent
+    assert_equal "rejected", error.message
+  end
+
+  private
+
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def post(body = '{"final":false}', timeout: 1, cancel: nil)
+    @transport.request("trace", body, deadline: monotonic + timeout, cancel: cancel) { |value| value["ok"] == true }
+  end
+
+  def reset_transport
+    @transport.close
+    @transport = MirrorsSDK::Transport.new(@config)
+  end
+
+  def handle(socket)
+    line = socket.gets("\r\n").strip
+    headers = {}
+    while (header = socket.gets("\r\n")) && header != "\r\n"
+      key, value = header.strip.split(":", 2)
+      headers[key.downcase] = value.strip
+    end
+    request = { line: line, headers: headers, body: socket.read(headers.fetch("content-length", "0").to_i) }
+    @requests << request
+    @behavior.call(socket, request)
+  rescue IOError, SystemCallError
+    nil
+  ensure
+    socket.close unless socket.closed?
+  end
+
+  def respond(socket, body: '{"ok":true}', status: 200, headers: "")
+    socket.write("HTTP/1.1 #{status} Result\r\nContent-Length: #{body.bytesize}\r\nConnection: close\r\n#{headers}\r\n#{body}")
+  end
+
+  def encode(data, encoding)
+    return data unless encoding
+    return Zlib::Deflate.deflate(data) if encoding == "deflate"
+
+    output = StringIO.new
+    writer = Zlib::GzipWriter.new(output)
+    writer.write(data)
+    writer.close
+    output.string
+  end
+end

data/test/wire_test.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "mirrors_sdk/wire"
+
+class WireTest < Minitest::Test
+  def trace(**extra)
+    { "id" => "run-1", "messages" => [{ "role" => "user", "content" => "Hello" }] }.merge(extra.transform_keys(&:to_s))
+  end
+
+  def utc(offset = 0)
+    (Time.now + offset).utc.iso8601(3)
+  end
+
+  def capture(final = false)
+    request = { "protocol" => 3, "agentId" => "agent", "requestId" => "request", "ordinal" => 1,
+                "trace" => trace, "final" => final, "captureOnly" => true }
+    response = { "protocol" => 3, "agentId" => "agent", "traceId" => "run-1", "requestId" => "request",
+                 "ordinal" => 1, "final" => final, "captureOnly" => true, "decisionId" => "decision",
+                 "expiresAt" => utc(1), "mode" => "active", "role" => "system", "context" => nil,
+                 "ingestion" => final ? { "status" => "queued", "jobId" => "job" } : nil }
+    [request, response]
+  end
+
+  def context
+    request = { "protocol" => 1, "agentId" => "agent", "requestId" => "request", "trace" => trace }
+    response = { "protocol" => 1, "agentId" => "agent", "requestId" => "request", "traceId" => "run-1",
+                 "decisionId" => "decision", "issuedAt" => utc(-0.1), "expiresAt" => utc(1), "mode" => "active",
+                 "modeVersion" => "version", "role" => "system", "context" => "fix", "reason" => "selected" }
+    [request, response]
+  end
+
+  def test_shared_canonical_fixture_is_preserved
+    fixture = JSON.parse(File.read(File.join(__dir__, "fixtures/canonical-events.json")))
+    ["../../python-sdk/tests/fixtures/canonical-events.json", "../../remote-sdk/test/fixtures/canonical-events.json"].each do |path|
+      source = File.expand_path(path, __dir__)
+      assert_equal JSON.parse(File.read(source)), fixture if File.exist?(source)
+    end
+    messages = fixture["events"][0]["data"]
+    source = trace(messages: messages)
+    assert_equal source, MirrorsSDK::Wire.snapshot(source)
+  end
+
+  def test_conversation_user_and_latency_rules
+    source = trace(conversationId: "chat", conversationRevision: 7,
+                   user: { "id" => "\ufeffuser\ufeff", "segment" => " founders " }, turnLatencyMs: 0.25)
+    copied = MirrorsSDK::Wire.snapshot(source, final: true, terminal: "failed")
+    assert_equal({ "id" => "user", "segment" => "founders" }, copied["user"])
+    assert_equal "\ufeffuser\ufeff", source["user"]["id"]
+    assert_equal 0.25, copied["turnLatencyMs"]
+    [0, -1, 1.5, true, 9_007_199_254_740_992].each do |revision|
+      assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(trace(conversationId: "chat", conversationRevision: revision)) }
+    end
+    assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(trace(conversationId: "chat")) }
+    assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(source) }
+    assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(trace, terminal: "completed") }
+    [true, -1, Float::INFINITY].each do |latency|
+      assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(trace(turnLatencyMs: latency), final: true) }
+    end
+  end
+
+  def test_agent_context_matches_prompt_and_skill_limits
+    ["", "  Original prompt\n", "💡" * 50_000].each do |prompt|
+      source = trace(agentContext: { "systemPrompt" => prompt, "skills" => [{ "name" => "search", "content" => "Find evidence" }] })
+      assert_equal source, MirrorsSDK::Wire.snapshot(source)
+    end
+    assert_equal({ "skills" => [] }, MirrorsSDK::Wire.snapshot(trace(agentContext: { "skills" => [] }))["agentContext"])
+    [{}, nil, { "systemPrompt" => nil }, { "systemPrompt" => "💡" * 50_001 },
+     { "systemPrompt" => "界" * 87_376 }, { "skills" => [{ "name" => " ", "content" => "x" }] },
+     { "skills" => [{ "name" => "a", "content" => "" }] },
+     { "skills" => Array.new(2) { { "name" => "same", "content" => "x" } } },
+     { "skills" => [{ "name" => "a\n", "content" => "x" }] },
+     { "systemPrompt" => "x", "unknown" => true }].each do |agent_context|
+      assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(trace(agentContext: agent_context)) }
+    end
+    boundary = trace(agentContext: { "systemPrompt" => "界" * 87_375 })
+    assert_equal 262_144, MirrorsSDK::Wire.encode(boundary["agentContext"]).bytesize
+    assert_equal boundary, MirrorsSDK::Wire.snapshot(boundary)
+  end
+
+  def test_invalid_fields_and_unicode_limits_do_not_silently_change_evidence
+    [trace(extra: 1), trace(id: "résumé"), trace(entryPoint: "💡" * 129),
+     trace(user: { "id" => "a\u001cb" }), trace(user: { "id" => "💡" * 129 }),
+     trace(messages: [{ "role" => "assistant", "content" => [{ "type" => "tool-call", "callId" => "c", "name" => "t" }] }]),
+     trace(messages: [{ "role" => "tool", "content" => [{ "type" => "tool-result", "callId" => "c", "name" => "t", "value" => nil, "error" => 1 }] }])].each do |source|
+      assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(source) }
+    end
+  end
+
+  def test_capture_receipts_require_exact_bindings_and_flags
+    [false, true].each do |final|
+      request, response = capture(final)
+      assert MirrorsSDK::Wire.trace_response(response, request)
+      { "ordinal" => 1.0, "final" => 1, "agentId" => "other", "traceId" => "other", "protocol" => true,
+        "context" => "injection", "captureOnly" => 1, "expiresAt" => "2026-02-30T00:00:00.000Z" }.each do |field, invalid|
+        refute MirrorsSDK::Wire.trace_response(response.merge(field => invalid), request), field
+      end
+      %w[context ingestion captureOnly].each do |field|
+        refute MirrorsSDK::Wire.trace_response(response.reject { |key, _| key == field }, request)
+      end
+      bad_ingestion = final ? nil : { "status" => "queued", "jobId" => "job" }
+      refute MirrorsSDK::Wire.trace_response(response.merge("ingestion" => bad_ingestion), request)
+    end
+  end
+
+  def test_context_bindings_shadow_and_mode_lease_limits
+    request, response = context
+    assert MirrorsSDK::Wire.context_response(response, request)
+    { "expiresAt" => utc(6), "issuedAt" => utc(2), "context" => "é" * 16_385,
+      "mode" => "shadow", "protocol" => true, "modeVersion" => "bad/value", "shadowOnly" => false }.each do |field, invalid|
+      refute MirrorsSDK::Wire.context_response(response.merge(field => invalid), request), field
+    end
+    assert MirrorsSDK::Wire.context_response(response.merge("shadowOnly" => true, "mode" => "shadow", "context" => nil),
+                                            request.merge("shadowOnly" => true))
+    mode = { "protocol" => 1, "agentId" => "agent", "mode" => "active", "version" => "v",
+             "issuedAt" => utc(-0.1), "expiresAt" => utc(1) }
+    assert MirrorsSDK::Wire.mode_response(mode, "agent")
+    refute MirrorsSDK::Wire.mode_response(mode.merge("expiresAt" => utc(4)), "agent")
+    refute MirrorsSDK::Wire.mode_response(mode.merge("agentId" => "other"), "agent")
+  end
+
+  def test_dates_are_canonical_calendar_dates_with_milliseconds
+    assert_equal 1_767_225_600, MirrorsSDK::Wire.utc("2026-01-01T00:00:00.000Z")
+    ["2026-01-01T00:00:00Z", "2026-01-01T00:00:00.000+00:00", "2026-02-30T00:00:00.000Z", nil].each do |invalid|
+      assert_raises(ArgumentError) { MirrorsSDK::Wire.utc(invalid) }
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: mirrors-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mirrors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Capture canonical conversation history and retrieve bounded, server-selected
+  context while your application owns model calls and tools.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- lib/mirrors_sdk.rb
+- lib/mirrors_sdk/agent_context.rb
+- lib/mirrors_sdk/capture.rb
+- lib/mirrors_sdk/circuit.rb
+- lib/mirrors_sdk/client.rb
+- lib/mirrors_sdk/configuration.rb
+- lib/mirrors_sdk/context.rb
+- lib/mirrors_sdk/delivery.rb
+- lib/mirrors_sdk/executor.rb
+- lib/mirrors_sdk/models.rb
+- lib/mirrors_sdk/snapshot.rb
+- lib/mirrors_sdk/transport.rb
+- lib/mirrors_sdk/version.rb
+- lib/mirrors_sdk/wire.rb
+- lib/mirrors_sdk/worker.rb
+- mirrors-sdk.gemspec
+- skills/install-mirrors-ruby-sdk/SKILL.md
+- test/capture_test.rb
+- test/configuration_test.rb
+- test/context_test.rb
+- test/executor_test.rb
+- test/fixtures/canonical-events.json
+- test/integration_test.rb
+- test/lifecycle_test.rb
+- test/snapshot_test.rb
+- test/support/runtime_server.rb
+- test/test_helper.rb
+- test/transport_test.rb
+- test/wire_test.rb
+homepage: https://mirrors.dev/docs
+licenses: []
+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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Background trace capture and optional context for Ruby agents
+test_files: []