mirrors-sdk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8031ec5dde9188cd42bfdad78edf5b7f94d09a7db3258f2b25c94e1acaa7ed49
-  data.tar.gz: c138edebf9c993de0264c19110774d49e283c7a91237054e17f23bc33b222896
+  metadata.gz: 25ae33b5a913fbdf8f66e8f1673ece8e8c9a206716efabc5151272d7dca57e42
+  data.tar.gz: 71d38ed8938e392792f47c848af98820ac3b532f8d555d8aabb919b4f912310c
 SHA512:
-  metadata.gz: 6c7b2b4237c20df46c699b4b9e6857b31da3d3a03982340719fef7c45ab3d4ef1a5c79342016b465a338c76543665d45d66a6c40611a478862da78dcc85b67ce
-  data.tar.gz: 206264fe2b5ed439310c831743aff066007e31279743f063c866061ae8aacc55162ccc3e88295aa4bfe78f76995e86a4a9e321fd81e4286f850859021342523b
+  metadata.gz: c35f3460533c74ca03136cc903182d269c4db2a46b3c6f95bcc2fe059b7c4e619340f8305dbfe08b17ffed4af65feed6a2e96644f9ee9da89ab9b37639a3c085
+  data.tar.gz: 74b8a1d425009f49dfa5bc978d149ff9e5e4878ae2fb536771013f98428d0f9bc5951c0e1fb5173bddfa8865c3dd7bd6aeab618960741b2ad5698c3860bf69e2

data/README.md

@@ -7,13 +7,13 @@ calls, tools, streaming, errors and cancellation.
 Requires Ruby 3.3 or later. Install a released version from RubyGems:
 
 ```sh
-gem install mirrors-sdk -v 0.1.0
+gem install mirrors-sdk -v 0.2.0
 ```
 
 For an application using Bundler, add this to its Gemfile and run `bundle install`:
 
 ```ruby
-gem "mirrors-sdk", "~> 0.1.0", require: "mirrors_sdk"
+gem "mirrors-sdk", "~> 0.2.0", require: "mirrors_sdk"
 ```
 
 To test an unreleased version, build and install from a reviewed checkout:
@@ -21,7 +21,7 @@ To test an unreleased version, build and install from a reviewed checkout:
 ```sh
 cd packages/ruby-sdk
 gem build mirrors-sdk.gemspec
-gem install --local mirrors-sdk-0.1.0.gem --no-document
+gem install --local mirrors-sdk-0.2.0.gem --no-document
 ruby -rmirrors_sdk -e 'puts MirrorsSDK::VERSION'
 ```
 
@@ -36,6 +36,14 @@ is independent of the Python and TypeScript packages. The packaged
 [installation skill](skills/install-mirrors-ruby-sdk/SKILL.md) describes integration
 and verifies official publication before suggesting a registry install.
 
+### Upgrading from 0.1.0
+
+Version 0.2.0 removes `agentContext.skills`. Remove that field before upgrading;
+`agentContext` now requires exactly `{ "systemPrompt" => original_system_prompt }`.
+Omit the object when the prompt is unknown. A snapshot containing `skills` is
+rejected, including when a valid system prompt is present. Existing server readers
+remain compatible with 0.1.0 clients.
+
 ## Integrate with the existing model loop
 
 Create one reusable client per agent configuration **after worker processes fork**.
@@ -122,26 +130,24 @@ milliseconds. Measure the whole user turn, including context waiting, models,
 tools, retries and streaming. Put `turnLatencyMs` on final capture only, excluding
 capture delivery; omit unknown duration.
 
-## Optional original instructions
+## Optional original system prompt
 
-Attach application-supplied instructions once to the turn's trace:
+Attach the application's original system prompt once to the turn's trace:
 
 ```ruby
 trace["agentContext"] = {
-  "systemPrompt" => original_system_prompt,
-  "skills" => [{ "name" => "account-policy", "content" => application_skill_text }]
+  "systemPrompt" => original_system_prompt
 }
 ```
 
-Either field may be omitted; the object must contain at least one. Capture the
-original prompt before appending Mirrors context. Include `agentContext` explicitly
+The object requires exactly one `systemPrompt` string. Capture the original prompt
+before appending Mirrors context. Include `agentContext` explicitly
 on the final capture to retain it: values are never inherited from an earlier
-snapshot or another turn. Empty prompt or skills values mean explicitly empty;
-omit unknown values. The SDK does not read files, discover skills or assert that
-supplied skills ran. Preserve existing system messages without synthesizing copies.
+snapshot or another turn. An empty string means explicitly no prompt; omit
+`agentContext` when the prompt is unknown. Preserve existing system messages
+without synthesizing copies.
 Compatible API and worker readers are required; installing a gem does not deploy
-the service. Ruby supports both prompt and skill fields from the TypeScript
-contract; the current Python SDK accepts only the prompt field.
+the service. This prompt-only object matches the TypeScript and Python SDKs.
 
 ## Receipts, cancellation and shutdown
 
@@ -178,8 +184,7 @@ inherited across a fork stays inert; create a new client in the child process.
 | --- | --- |
 | Encoded snapshot | 1,000,000 bytes; 10,000 messages; 50,000 JSON nodes; depth 32 |
 | Agent context | 262,144 UTF-8 JSON bytes within the snapshot budget |
-| Prompt / each skill content | 100,000 UTF-16 code units |
-| Skills | 64 unique names; names at most 128 UTF-16 code units |
+| Original system prompt | 100,000 UTF-16 code units |
 | Pending captures | 16 prefixes and 16 finals, independently |
 | Active executions / recent final receipts | 64 / 128 |
 | Pending retrievals | 16, independent of capture |
@@ -219,7 +224,7 @@ hosted Mirrors service.
 ## Publishing through GitHub Actions
 
 The `Ruby SDK` workflow publishes tags named `ruby-sdk-v<VERSION>`, such as
-`ruby-sdk-v0.1.0`. All three Ruby versions must pass verification before the
+`ruby-sdk-v0.2.0`. All three Ruby versions must pass verification before the
 `publish` job can upload the exact gem built and tested by the Ruby 3.4 job.
 Pull requests and manual workflow runs only verify; they never publish.
 
@@ -258,8 +263,8 @@ TypeScript packages. Merge the reviewed SDK and workflow, then tag the intended
 merged commit after its checks pass:
 
 ```sh
-git tag ruby-sdk-v0.1.0 <verified-merged-commit>
-git push origin refs/tags/ruby-sdk-v0.1.0
+git tag ruby-sdk-v0.2.0 <verified-merged-commit>
+git push origin refs/tags/ruby-sdk-v0.2.0
 ```
 
 The tag must exactly match `MirrorsSDK::VERSION`; the publish job also checks the

data/lib/mirrors_sdk/agent_context.rb

@@ -3,49 +3,24 @@
 require "json"
 
 module MirrorsSDK
-  # Original instructions are optional evidence, never modifications to model input.
+  # The original system prompt is optional evidence, never a modification to model input.
   class AgentContextWire
-    TRIM = /\A[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+|[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+\z/.freeze
-
     def self.length(value)
       value.encode(Encoding::UTF_16LE).bytesize / 2
     end
 
     def self.validate(value)
-      unless value.instance_of?(Hash) && !value.empty? && (value.keys - %w[systemPrompt skills]).empty?
-        raise ArgumentError, "Invalid agent context"
+      unless value.instance_of?(Hash) && value.keys == ["systemPrompt"]
+        raise ArgumentError, "Agent context requires a systemPrompt field"
       end
-      if value.key?("systemPrompt")
-        prompt = value["systemPrompt"]
-        unless prompt.instance_of?(String) && length(prompt) <= 100_000
-          raise ArgumentError, "Invalid system prompt"
-        end
+      prompt = value["systemPrompt"]
+      unless prompt.instance_of?(String) && length(prompt) <= 100_000
+        raise ArgumentError, "Invalid system prompt"
       end
-      validate_skills(value["skills"]) if value.key?("skills")
       if JSON.generate(value).bytesize > 262_144
         raise ArgumentError, "Agent context exceeds the encoded size limit"
       end
       value
     end
-
-    def self.validate_skills(skills)
-      unless skills.instance_of?(Array) && skills.length <= 64
-        raise ArgumentError, "Invalid agent skills"
-      end
-      names = {}
-      skills.each do |skill|
-        unless skill.instance_of?(Hash) && skill.keys.sort == %w[content name]
-          raise ArgumentError, "Invalid agent skill"
-        end
-        name, content = skill.values_at("name", "content")
-        unless name.instance_of?(String) && !name.gsub(TRIM, "").empty? &&
-               length(name) <= 128 && !name.match?(/\p{Cc}/) && !names[name] &&
-               content.instance_of?(String) && !content.empty? && length(content) <= 100_000
-          raise ArgumentError, "Invalid agent skill"
-        end
-        names[name] = true
-      end
-    end
-    private_class_method :validate_skills
   end
 end

data/lib/mirrors_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MirrorsSDK
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/mirrors_sdk/wire.rb

@@ -10,6 +10,7 @@ module MirrorsSDK
   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
+    TRIM = /\A[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+|[\s\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+\z/.freeze
 
     def self.encode(value, limit: 1_000_000, deadline: nil)
       Snapshot.encode(value, limit: limit, deadline: deadline)
@@ -207,7 +208,7 @@ module MirrorsSDK
       { "id" => 256, "segment" => 64 }.each do |field, limit|
         next unless value.key?(field)
 
-        trimmed = text(value[field]).gsub(AgentContextWire::TRIM, "")
+        trimmed = text(value[field]).gsub(TRIM, "")
         unless AgentContextWire.length(trimmed).between?(1, limit) && !trimmed.match?(/\p{Cc}/)
           raise ArgumentError, "Invalid end user"
         end

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

@@ -124,15 +124,16 @@ execution, persist the pair and keep it fixed across snapshots/retries. Timestam
 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
+## Optional original system prompt
 
 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.
+instructions as `trace["agentContext"] = { "systemPrompt" => original_system_prompt }`.
+Read the application's prompt before adding Mirrors context. The object accepts
+only the `systemPrompt` string; do not load arbitrary files automatically. Include
+it on the final snapshot: previous values are never inherited. Omit `agentContext`
+when the prompt is unknown; an empty string explicitly means no prompt. Respect
+the installed README's character and byte limits. Preserve existing system messages
+without synthesizing copies.
 
 ## Verify and shut down
 

data/test/integration_test.rb

@@ -17,7 +17,7 @@ class IntegrationTest < Minitest::Test
   def test_capture_and_context_match_existing_protocols
     wait_for_active
     evidence = trace.merge("conversationId" => "chat", "conversationRevision" => 3,
-                           "agentContext" => { "systemPrompt" => "Original prompt", "skills" => [{ "name" => "search", "content" => "Search first" }] })
+                           "agentContext" => { "systemPrompt" => "Original prompt" })
     prefix = @client.capture_trace(evidence)
     result = @client.get_context(evidence)
     assert_equal @server.context_text, result.context
@@ -33,6 +33,7 @@ class IntegrationTest < Minitest::Test
     assert_equal 12.5, captures.last[:body]["trace"]["turnLatencyMs"]
     request = @server.requests("retrieve-context").last
     assert_equal 1, request[:body]["protocol"]
+    assert_equal({ "systemPrompt" => "Original prompt" }, request[:body]["trace"]["agentContext"])
     assert_equal Digest::SHA256.hexdigest("retrieve-context\n#{request[:raw]}"), request[:headers]["idempotency-key"]
     assert_equal "execution_closed", @client.get_context(evidence).reason
   end
@@ -40,13 +41,15 @@ class IntegrationTest < Minitest::Test
   def test_capture_does_not_wait_for_http_or_hold_context
     wait_for_active
     @server.capture_delay = 0.2
-    evidence = trace
+    evidence = trace.merge("agentContext" => { "systemPrompt" => "Original prompt" })
     started = monotonic
     ticket = @client.capture_trace(evidence)
     assert_operator monotonic - started, :<, 0.1
     evidence["messages"][0]["content"] = "Mutated after capture"
+    evidence["agentContext"]["systemPrompt"] = "Mutated after capture"
     eventually { @server.requests("trace").any? }
     assert_equal "Hello", @server.requests("trace").first[:body]["trace"]["messages"][0]["content"]
+    assert_equal "Original prompt", @server.requests("trace").first[:body]["trace"]["agentContext"]["systemPrompt"]
     assert_equal @server.context_text, @client.get_context(trace).context
     assert_equal "pending", ticket.receipt.status
     assert_equal "accepted", ticket.wait(1).status
@@ -111,17 +114,34 @@ class IntegrationTest < Minitest::Test
 
   def test_uncertain_prefix_replays_identical_bytes_before_final
     @server.capture_failures = 1
-    prefix = @client.capture_trace(trace)
+    evidence = trace.merge("agentContext" => { "systemPrompt" => "Original prompt" })
+    prefix = @client.capture_trace(evidence)
     assert_equal "unconfirmed", prefix.wait(1).status
-    final = @client.capture_trace(trace, final: true, terminal: "completed")
+    evidence["agentContext"]["systemPrompt"] = "Final prompt"
+    final = @client.capture_trace(evidence, final: true, terminal: "completed")
     assert_equal "accepted", final.wait(1).status
     records = @server.requests("trace")
     assert_equal 3, records.length
     assert_equal records[0][:raw], records[1][:raw]
     assert_equal records[0][:headers]["idempotency-key"], records[1][:headers]["idempotency-key"]
+    assert_equal "Original prompt", records[1][:body]["trace"]["agentContext"]["systemPrompt"]
+    assert_equal "Final prompt", records[2][:body]["trace"]["agentContext"]["systemPrompt"]
     assert_equal 2, records[2][:body]["ordinal"]
-    assert_same final, @client.capture_trace(trace, final: true, terminal: "completed")
-    assert_equal "terminal_conflict", @client.capture_trace(trace, final: true, terminal: "failed").receipt.reason
+    assert_same final, @client.capture_trace(evidence, final: true, terminal: "completed")
+    assert_equal "terminal_conflict", @client.capture_trace(evidence, final: true, terminal: "failed").receipt.reason
+  end
+
+  def test_skills_reject_capture_and_context_without_http
+    wait_for_active
+    [{ "skills" => [] }, { "systemPrompt" => "Original prompt", "skills" => [] }].each_with_index do |context, index|
+      evidence = trace("invalid-context-#{index}").merge("agentContext" => context)
+      result = @client.get_context(evidence)
+      assert_empty result.context
+      assert_equal "invalid_evidence", result.reason
+      assert_equal "invalid_evidence", @client.capture_trace(evidence).receipt.reason
+    end
+    assert_empty @server.requests("trace")
+    assert_empty @server.requests("retrieve-context")
   end
 
   def test_flush_snapshots_pending_and_close_disposes

data/test/wire_test.rb

@@ -32,7 +32,7 @@ class WireTest < Minitest::Test
 
   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|
+    ["../../python-sdk/tests/fixtures/canonical-events.json", "../../typescript-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
@@ -59,17 +59,20 @@ class WireTest < Minitest::Test
     end
   end
 
-  def test_agent_context_matches_prompt_and_skill_limits
+  def test_agent_context_copies_original_prompt_and_enforces_limits
+    refute MirrorsSDK::Wire.snapshot(trace).key?("agentContext")
     ["", "  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)
+      source = trace(agentContext: { "systemPrompt" => prompt })
+      copied = MirrorsSDK::Wire.snapshot(source)
+      assert_equal source, copied
+      refute_same source["agentContext"], copied["agentContext"]
+      source["agentContext"]["systemPrompt"] = "Changed after capture"
+      assert_equal prompt, copied["agentContext"]["systemPrompt"]
     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" => "界" * 87_376 }, { "skills" => [] },
+     { "systemPrompt" => "x", "skills" => [] },
+     { "systemPrompt" => "x", "skills" => [{ "name" => "search", "content" => "Find evidence" }] },
      { "systemPrompt" => "x", "unknown" => true }].each do |agent_context|
       assert_raises(ArgumentError) { MirrorsSDK::Wire.snapshot(trace(agentContext: agent_context)) }
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mirrors-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mirrors