bitfab 0.9.0 → 0.10.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78b34044dcc028414fb2f6fbe020f98bf0ce1a953507c8939bc12d8c15630b09
-  data.tar.gz: 174aa2eb61c2aca0a11078f2361b4392d7612f2a582e3dd4046608cbbb539a27
+  metadata.gz: b789df310c91a7e9130f3bdb6a35e6237a8ddadede4df49a5f7dc4afc0525e91
+  data.tar.gz: 0cd79b9c9bc8bf15ef926625c0aa1aba8f3cf1798062c0d077e371d98b9f6aba
 SHA512:
-  metadata.gz: d2eeec89057ecdee5f7f5eae5342ad9218aa190fc472aa01d3dbf0323262b33165faed2d61d6ae0be9bf7da3af9a7e88902e0fa426344b53751b78d0c1f5cf18
-  data.tar.gz: 9726da71f354723007ff6b9bf38466544e93a1ae21f0b02e2b258827697d4996caea781d1c062c7386dd5508eddad097fbc85f4382798e07cd11a0535a6e1a7a
+  metadata.gz: fbf62eeabc5741c36ef1b867730f548039f20331d6591ccae7a66cc48882cd4638877edc1b80d57c3a326827edfbedff1d3ec226ed3b4e3358f9041e3405ea5f
+  data.tar.gz: 579cb384585a42160d5f1c9941cbf0762f53d35ffda7f109cb40c4c52a291a02d446e113ca664a2c84a08916481fe86912eb386a58956fb5651ff1a6dc108771

data/lib/bitfab/client.rb

@@ -36,9 +36,18 @@ module Bitfab
     # @param limit [Integer] maximum number of traces to replay (default: 5)
     # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
+    # @param code_change_description [String, nil] optional rationale for the
+    #   code change being tested in this replay (stored on the experiment)
+    # @param code_change_files [Array<Hash>, nil] optional list of edited files,
+    #   each as { path:, before:, after: } (use "" for new/deleted files)
     # @return [Hash] with :items, :test_run_id, :test_run_url
-    def replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10)
-      Replay.run(self, receiver, method_name, trace_function_key:, limit:, trace_ids:, max_concurrency:)
+    def replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10,
+      code_change_description: nil, code_change_files: nil)
+      Replay.run(
+        self, receiver, method_name,
+        trace_function_key:, limit:, trace_ids:, max_concurrency:,
+        code_change_description:, code_change_files:
+      )
     end
 
     # Execute a block inside a span context, sending trace data on completion.
@@ -53,9 +62,13 @@ module Bitfab
       is_root_span = parent_span_id.nil?
       started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
+      replay_ctx = ReplayContext.current
+      resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+      resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
+
       # Register trace state for root spans
       if is_root_span && !TraceState.get(trace_id)
-        TraceState.create(trace_id)
+        TraceState.create(trace_id, test_run_id: resolved_test_run_id)
       end
 
       if is_root_span
@@ -66,27 +79,18 @@ module Bitfab
       error = nil
       span_contexts = nil
       span_prompt = nil
+      finalized = false
+
+      finalize = lambda do |final_result, final_error|
+        # Never crash the host app due to span building/sending. Idempotent —
+        # only the first call sends the span. Subsequent calls (e.g. from the
+        # enumerator wrapper after iteration completes) are no-ops.
+        next if finalized
+        finalized = true
 
-      begin
-        SpanContext.with_span(trace_id:, span_id:) do
-          result = yield
-        ensure
-          # Capture contexts before the span context is popped
-          span_contexts = SpanContext.current&.dig(:contexts)
-          span_prompt = SpanContext.current&.dig(:prompt)
-        end
-      rescue => e
-        error = e.message
-        raise
-      ensure
-        # Never crash the host app due to span building/sending
         begin
           ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
-          replay_ctx = ReplayContext.current
-          resolved_test_run_id = replay_ctx&.dig(:test_run_id)
-          resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
-
           span_thread = send_span(
             trace_function_key:,
             trace_id:,
@@ -99,8 +103,8 @@ module Bitfab
             prompt: span_prompt,
             args:,
             kwargs:,
-            result:,
-            error:,
+            result: final_result,
+            error: final_error,
             started_at:,
             ended_at:,
             test_run_id: resolved_test_run_id,
@@ -130,11 +134,78 @@ module Bitfab
         end
       end
 
+      begin
+        SpanContext.with_span(trace_id:, span_id:) do
+          result = yield
+        ensure
+          # Capture contexts before the span context is popped
+          span_contexts = SpanContext.current&.dig(:contexts)
+          span_prompt = SpanContext.current&.dig(:prompt)
+        end
+      rescue => e
+        error = e.message
+        finalize.call(result, error)
+        raise
+      end
+
+      # If the wrapped block returned an Enumerator (lazy iteration via
+      # `enum_for`, `to_enum`, `Enumerator.new`, `[...].lazy.map(...)`, etc.),
+      # the work hasn't actually run yet — the values are produced as the
+      # caller iterates. Without special handling we'd close the span here
+      # with `result == <the Enumerator object>`, and any nested `bitfab_span`
+      # calls inside the enumerator body would see an empty span stack and
+      # post their own root traces, fragmenting one logical workflow.
+      #
+      # Instead, hand the caller a wrapping Enumerator whose body restores
+      # the parent span stack on the iterating fiber, drives the source,
+      # collects yielded values as the span output, and finalizes the span
+      # once iteration completes (or errors).
+      #
+      # Limitation: when the source enumerator itself runs its body in a
+      # separate fiber (e.g. `Enumerator.new { |y| ... }` or `enum_for(...)`
+      # without a block), nested `bitfab_span` calls inside that body fiber
+      # still see an empty stack because `Thread.current[STACK_KEY]` is
+      # fiber-local. Lazy chains over collections (`.lazy.map`) and ordinary
+      # `each` callbacks DO run in the iterating fiber and nest correctly.
+      if result.is_a?(Enumerator)
+        return wrap_enumerator(result, trace_id:, span_id:, finalize:)
+      end
+
+      finalize.call(result, error)
       result
     end
 
     private
 
+    # Build an Enumerator that drives `source`, restoring `[trace_id, span_id]`
+    # on the iterating fiber so nested `bitfab_span` calls inside lazy / `each`
+    # callbacks nest under the parent span. Yielded values are collected as the
+    # span output. The span is sent exactly once — when iteration finishes,
+    # raises, or the wrapper is `.close`d.
+    def wrap_enumerator(source, trace_id:, span_id:, finalize:)
+      span_entry = {trace_id:, span_id:}
+      yielded = []
+
+      Enumerator.new do |yielder|
+        # Push our span onto this fiber's stack so anything that runs in this
+        # fiber (including the user's lazy block and `each` callbacks) sees
+        # the right parent.
+        SpanContext.stack.push(span_entry)
+        begin
+          source.each do |value|
+            yielded << value
+            yielder << value
+          end
+          finalize.call(yielded, nil)
+        rescue => e
+          finalize.call(yielded, e.message)
+          raise
+        ensure
+          SpanContext.stack.pop
+        end
+      end
+    end
+
     def validate_span_type!(type)
       return if SPAN_TYPES.include?(type.to_s)
 
@@ -169,6 +240,9 @@ module Bitfab
       if trace_state&.dig(:session_id)
         payload["sessionId"] = trace_state[:session_id]
       end
+      if trace_state&.dig(:test_run_id)
+        payload["testRunId"] = trace_state[:test_run_id]
+      end
 
       @http_client.send_external_trace(payload)
 

data/lib/bitfab/http_client.rb

@@ -98,12 +98,19 @@ module Bitfab
 
     # Start a replay session by fetching historical traces.
     # Blocking call. Returns hash with testRunId, testRunUrl, and items array.
-    def start_replay(trace_function_key, limit, trace_ids: nil)
+    #
+    # @param code_change_description [String, nil] optional rationale for the
+    #   code change being tested in this replay
+    # @param code_change_files [Array<Hash>, nil] optional list of edited files,
+    #   each as { path:, before:, after: } (use "" for new/deleted files)
+    def start_replay(trace_function_key, limit, trace_ids: nil, code_change_description: nil, code_change_files: nil)
       payload = {
         "traceFunctionKey" => trace_function_key,
         "limit" => limit
       }
       payload["traceIds"] = trace_ids if trace_ids
+      payload["codeChangeDescription"] = code_change_description unless code_change_description.nil?
+      payload["codeChangeFiles"] = normalize_code_change_files(code_change_files) unless code_change_files.nil?
 
       request("/api/sdk/replay/start", payload, timeout: 30)
     end
@@ -129,6 +136,18 @@ module Bitfab
 
     private
 
+    # Normalize each entry to a hash with stable string keys, accepting either
+    # symbol-keyed or string-keyed hashes from callers.
+    def normalize_code_change_files(files)
+      files.map do |file|
+        {
+          "path" => file[:path] || file["path"],
+          "before" => file[:before] || file["before"],
+          "after" => file[:after] || file["after"]
+        }
+      end
+    end
+
     def headers
       {
         "Content-Type" => "application/json",

data/lib/bitfab/replay.rb

@@ -42,11 +42,22 @@ module Bitfab
     # @param limit [Integer] maximum number of traces to replay (default: 5)
     # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
+    # @param code_change_description [String, nil] optional rationale for the
+    #   code change being tested in this replay (stored on the experiment)
+    # @param code_change_files [Array<Hash>, nil] optional list of edited files,
+    #   each as { path:, before:, after: } (empty string for new/deleted files)
     # @return [Hash] with :items, :test_run_id, :test_run_url
-    def run(client, receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10)
+    def run(client, receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10,
+      code_change_description: nil, code_change_files: nil)
       http_client = client.instance_variable_get(:@http_client)
 
-      replay_data = http_client.start_replay(trace_function_key, limit, trace_ids:)
+      replay_data = http_client.start_replay(
+        trace_function_key,
+        limit,
+        trace_ids:,
+        code_change_description:,
+        code_change_files:
+      )
       test_run_id = replay_data["testRunId"]
       test_run_url = replay_data["testRunUrl"]
       server_items = replay_data["items"] || []
@@ -105,7 +116,8 @@ module Bitfab
     def process_single_item(http_client, server_item, receiver, method_name, test_run_id)
       span = http_client.get_external_span(server_item["externalSpanId"])
       item_data = extract_span_data(span)
-      execute_item(item_data, receiver, method_name, test_run_id, span["id"])
+      metrics = extract_server_item_metrics(server_item)
+      execute_item(item_data, receiver, method_name, test_run_id, span["id"], metrics)
     end
 
     # Extract input/output data from an external span's rawData.
@@ -121,8 +133,29 @@ module Bitfab
       }
     end
 
+    # Pull durationMs / tokens / model from the start-replay server item.
+    # Normalizes to symbol-keyed tokens hash and nil-safe defaults so older
+    # servers without these fields still produce a consistent shape.
+    def extract_server_item_metrics(server_item)
+      raw_tokens = server_item["tokens"]
+      tokens = if raw_tokens.is_a?(Hash)
+        {
+          input: raw_tokens["input"],
+          output: raw_tokens["output"],
+          cached: raw_tokens["cached"],
+          total: raw_tokens["total"]
+        }
+      end
+
+      {
+        duration_ms: server_item["durationMs"],
+        tokens:,
+        model: server_item["model"]
+      }
+    end
+
     # Execute a single replay item: deserialize inputs, call method with replay context.
-    def execute_item(item, receiver, method_name, test_run_id, input_source_span_id = nil)
+    def execute_item(item, receiver, method_name, test_run_id, input_source_span_id = nil, metrics = {})
       args, kwargs = Serialize.deserialize_inputs(item)
 
       fn_result = nil
@@ -142,7 +175,10 @@ module Bitfab
         input: args,
         result: fn_result,
         original_output: item["output"],
-        error: fn_error
+        error: fn_error,
+        duration_ms: metrics[:duration_ms],
+        tokens: metrics[:tokens],
+        model: metrics[:model]
       }
     end
   end

data/lib/bitfab/span_context.rb

@@ -131,12 +131,13 @@ module Bitfab
       @states_mutex.synchronize { @states[trace_id] }
     end
 
-    def create(trace_id)
+    def create(trace_id, test_run_id: nil)
       @states_mutex.synchronize do
         @states[trace_id] ||= {
           trace_id:,
-          started_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
-        }
+          started_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ"),
+          test_run_id:
+        }.compact
       end
     end
 

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.9.0"
+  VERSION = "0.10.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.5
 platform: ruby
 authors:
 - Harvest Team