coolhand 0.7.0 → 0.9.0

data/lib/coolhand/open_ai/batch_result_processor.rb

@@ -16,7 +16,9 @@ module Coolhand
 
         case batch_info["status"]
         when "completed"
-          process_completed_batch
+          # Downloads two files and POSTs one log per item — run it on the background log queue so
+          # the webhook response isn't held up for the whole batch.
+          LogQueue.submit(lane: :batch) { process_completed_batch_logging_errors }
         when "failed", "expired", "cancelled"
           handle_failed_batch
         when "in_progress", "validating", "finalizing"
@@ -30,6 +32,14 @@ module Coolhand
 
       private
 
+      # Runs on the batch lane's worker thread, where an escaping error would only reach
+      # Coolhand.log (silenceable) rather than the Rails log `call` reports to.
+      def process_completed_batch_logging_errors
+        process_completed_batch
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to process OpenAI batch results for #{event_data}: #{e.message}")
+      end
+
       def process_completed_batch
         input_file_id = batch_info["input_file_id"]
         return unless input_file_id
@@ -43,8 +53,12 @@ module Coolhand
         # Download and process results
         batch_response_items = download_batch_results(output_file_id)
 
+        request_items_by_id = batch_request_items.each_with_object({}) do |item, index|
+          index[item["custom_id"]] ||= item
+        end
+
         batch_response_items.each do |response_item|
-          request_item = batch_request_items.detect { |item| item["custom_id"] == response_item["custom_id"] }
+          request_item = request_items_by_id[response_item["custom_id"]]
 
           next unless request_item
 
@@ -89,33 +103,20 @@ module Coolhand
 
       def send_complete_request_log(request_id:, method:, url:, request_body:, response_body:, status_code:,
         start_time:, end_time:)
-        timestamp = Time.at(start_time).iso8601
-        completed_at = Time.at(end_time).iso8601
-        duration_ms = ((end_time - start_time) * 1000).to_i
-
-        request_data = {
-          raw_request: {
-            id: request_id,
-            timestamp: timestamp,
-            method: method.to_s.downcase,
-            url: BaseInterceptor.sanitize_url(url),
-            headers: {},
-            request_body: request_body,
-            response_headers: {},
-            response_body: response_body,
-            status_code: status_code,
-            duration_ms: duration_ms,
-            completed_at: completed_at,
-            is_streaming: false
-          }
-        }
-
-        api_service = Coolhand::ApiService.new
-        api_service.send_llm_request_log(request_data)
-
-        Coolhand.log "📤 Sent complete request/response log for #{request_id} (duration: #{duration_ms}ms)"
-      rescue StandardError => e
-        Coolhand.log "❌ Error sending complete request log: #{e.message}"
+        BaseInterceptor.send_complete_request_log(
+          request_id: request_id,
+          method: method,
+          url: url,
+          request_headers: {},
+          request_body: request_body,
+          response_headers: {},
+          response_body: response_body,
+          status_code: status_code,
+          start_time: Time.at(start_time),
+          end_time: Time.at(end_time),
+          duration_ms: ((end_time - start_time) * 1000).to_i,
+          is_streaming: false
+        )
       end
 
       def batch_info

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -7,6 +7,9 @@ require_relative "webhook_id_store"
 module Coolhand
   module OpenAi
     class WebhookValidator
+      SIGNATURE_VERSION_PREFIX = "v1,"
+      private_constant :SIGNATURE_VERSION_PREFIX
+
       attr_reader :request, :errors, :payload
 
       def initialize(request, webhook_secret)
@@ -41,27 +44,25 @@ module Coolhand
       def payload_valid?
         return true if @payload
 
-        if should_enforce_strict_validation?
-          @errors << "Empty webhook payload - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
-                     "not in development/test allowlist)"
-          Rails.logger.error(@errors.last)
-          false
-        else
-          Rails.logger.warn("Empty webhook payload - allowing in #{Rails.env} environment")
-          true
-        end
+        enforce_or_allow("Empty webhook payload",
+          "Empty webhook payload - allowing in #{Rails.env} environment")
       end
 
       def validate_in_non_production_env
+        enforce_or_allow("OpenAI webhook secret not configured",
+          "Webhook Secret is not configured - skipping signature verification in #{Rails.env}")
+      end
+
+      # Outside the development/test allowlist the webhook is rejected with `problem`; inside it the
+      # check is skipped with a warning.
+      def enforce_or_allow(problem, allow_warning)
         if should_enforce_strict_validation?
-          @errors << "OpenAI webhook secret not configured - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+          @errors << "#{problem} - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
                      "not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
-          Rails.logger.warn(
-            "Webhook Secret is not configured - skipping signature verification in #{Rails.env}"
-          )
+          Rails.logger.warn(allow_warning)
           true
         end
       end
@@ -99,8 +100,7 @@ module Coolhand
         expected_signature = calculate_expected_signature(secret_bytes, signed_payload)
 
         # An empty key (a bare "whsec_" secret) makes the HMAC forgeable by anyone, so never accept it.
-        signature_valid = !secret_bytes.empty? && webhook_signature.start_with?("v1,") &&
-                          secure_compare(webhook_signature[3..], expected_signature)
+        signature_valid = !secret_bytes.empty? && signature_matches?(webhook_signature, expected_signature)
 
         unless signature_valid
           @errors << "OpenAI webhook signature verification failed"
@@ -114,6 +114,18 @@ module Coolhand
         true
       end
 
+      # Standard Webhooks allows several space-separated signatures (e.g. during secret rotation);
+      # accept the request if any v1 entry matches. Every candidate is compared (`map`, not an
+      # `any?` block) so there is no early exit on the first match.
+      # Split as binary so a header that isn't valid UTF-8 is rejected rather than raising.
+      def signature_matches?(webhook_signature, expected_signature)
+        candidates = webhook_signature.b.split.select { |entry| entry.start_with?(SIGNATURE_VERSION_PREFIX) }
+        results = candidates.map do |entry|
+          secure_compare(entry.delete_prefix(SIGNATURE_VERSION_PREFIX), expected_signature)
+        end
+        results.any?
+      end
+
       # Checked only after the signature is confirmed valid, so an
       # unsigned/forged request can't poison the id-dedup store (or fail a
       # freshness check) and DoS a later legitimate webhook with the same id.

data/lib/coolhand/optimization_feedback_link_service.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "api_service"
+require_relative "write_requests"
+
+module Coolhand
+  # Requires the client's **private** key; the public key gets a 401. Unlike the logging writes,
+  # every method raises {Coolhand::Error} / {Coolhand::HttpError} on failure. See docs/feedback-links.md.
+  class OptimizationFeedbackLinkService < ApiService
+    include WriteRequests
+
+    ERROR_NOUN = "Feedback link"
+    # The server rejects more ids than this per request with a 422.
+    BULK_BATCH_SIZE = 100
+
+    def initialize
+      super("v2/optimizations")
+    end
+
+    # Returns `{ id:, optimization_id:, feedback_id:, note:, created_at: }`; `id` is the link's hashid.
+    def link_feedback(optimization_id, feedback_id, note: nil)
+      validate_id!("link_feedback", "feedback_id", feedback_id)
+      url = links_url("link_feedback", optimization_id)
+      ensure_object!(request_json(:post, url, ERROR_NOUN, body: { feedback_id: feedback_id.strip, note: note }.compact))
+    end
+
+    # Lists over 100 ids are sent in batches; a failing batch raises and earlier ones stay applied,
+    # so repeating the call is safe. Returns `{ linked:, already_linked:, errored:, not_found: }` summed
+    # across batches.
+    def bulk_link_feedback(optimization_id, feedback_ids, note: nil)
+      unless feedback_ids.is_a?(Array) && !feedback_ids.empty?
+        raise Error, "bulk_link_feedback: feedback_ids must be a non-empty array of hashids"
+      end
+
+      feedback_ids.each { |id| validate_id!("bulk_link_feedback", "feedback_ids entries", id) }
+      feedback_ids = feedback_ids.map(&:strip)
+      url = links_url("bulk_link_feedback", optimization_id)
+
+      totals = { linked: 0, already_linked: 0, errored: 0, not_found: [] }
+      feedback_ids.each_slice(BULK_BATCH_SIZE) do |batch|
+        result = request_json(:post, url, ERROR_NOUN, body: { feedback_ids: batch, note: note }.compact)
+        merge_bulk_result!(totals, result)
+      end
+      totals
+    end
+
+    # `link_id` is the `id` returned by {#link_feedback}, not the feedback's. Returns true.
+    def unlink_feedback(optimization_id, link_id)
+      validate_id!("unlink_feedback", "link_id", link_id)
+      url = URI.parse("#{links_url('unlink_feedback', optimization_id)}/#{escape_path_segment(link_id.strip)}")
+      request_json(:delete, url, ERROR_NOUN)
+      true
+    end
+
+    private
+
+    def merge_bulk_result!(totals, result)
+      ensure_object!(result)
+
+      %i[linked already_linked errored].each { |key| totals[key] += result[key].to_i }
+      totals[:not_found].concat(Array(result[:not_found]))
+    end
+
+    def ensure_object!(result)
+      raise Error, "#{ERROR_NOUN} response was not a JSON object" unless result.is_a?(Hash)
+
+      result
+    end
+
+    def links_url(method_name, optimization_id)
+      validate_id!(method_name, "optimization_id", optimization_id)
+      URI.parse("#{api_endpoint}/#{escape_path_segment(optimization_id.strip)}/feedback_links")
+    end
+
+    # A blank id would resolve to a different route and a bare dot segment would retarget the
+    # request; neither 404s, so both are rejected before any request is made.
+    def validate_id!(method_name, label, value)
+      trimmed = value.is_a?(String) ? value.strip : ""
+      return unless trimmed.empty? || [".", ".."].include?(trimmed)
+
+      raise Error, "#{method_name}: #{label} must be a non-empty hashid"
+    end
+  end
+end

data/lib/coolhand/rails_auto_declare.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Opt-in (`config.auto_declare`) declaration of the workload and template for LLM calls made from a
+  # Rails job or controller action, keyed "JobClass#perform" / "ControllerClass#action". Installed from
+  # {Railtie} once the app has configured Coolhand. Kept free of any Rails require: it only touches
+  # ActiveSupport and ActiveJob when a target is enabled, and only through their own load hooks.
+  module RailsAutoDeclare
+    REPORTER = "rails"
+    TARGETS = %i[active_job controller].freeze
+
+    @installed = []
+
+    module_function
+
+    def install(targets = Coolhand.configuration.auto_declare)
+      TARGETS.each do |target|
+        next unless targets.include?(target) && !@installed.include?(target)
+
+        @installed << target
+        send(:"hook_#{target}")
+      end
+    end
+
+    def hook_active_job
+      ActiveSupport.on_load(:active_job) do
+        around_perform do |job, block|
+          Coolhand::RailsAutoDeclare.declare(job.class, "perform", &block)
+        end
+      end
+    end
+
+    def hook_controller
+      ActiveSupport.on_load(:action_controller) do
+        around_action do |controller, block|
+          Coolhand::RailsAutoDeclare.declare(controller.class, controller.action_name, &block)
+        end
+      end
+    end
+
+    # Runs the block inside a declared context. Anonymous classes have no stable key, so they are left
+    # undeclared rather than named after an object id.
+    def declare(klass, method_name, &block)
+      key = "#{klass.name}##{method_name}"
+      return yield if klass.name.nil? || !Coolhand.configuration.enabled || !DeclaredContext.valid_key?(key)
+
+      Coolhand.with_context(reporter: REPORTER, workload: { key: key }, template: { key: key }, &block)
+    end
+
+    # Testing-only: forget which targets were hooked.
+    def reset!
+      @installed.clear
+    end
+  end
+end

data/lib/coolhand/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Loaded by lib/coolhand.rb only when Rails is present, so the gem keeps no Rails dependency.
+  class Railtie < ::Rails::Railtie
+    # After the app's initializers, so `config.auto_declare` has been set by `Coolhand.configure`.
+    config.after_initialize do
+      Coolhand::RailsAutoDeclare.install
+    end
+  end
+end

data/lib/coolhand/read_query.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "uri"
+require_relative "errors"
+require_relative "pagination"
+
+module Coolhand
+  # URL building shared by the read services. Everything goes through `URI.encode_www_form`, so a
+  # `+` UTC offset reaches the server as `%2B` instead of being read as a space.
+  module ReadQuery
+    protected
+
+    def list_url(query)
+      uri = URI.parse(api_endpoint)
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    # GETs a list endpoint and wraps the JSON array and its pagination headers in `result_class`,
+    # keyed by `rows_key` (the field the result struct names its rows by).
+    def fetch_list(query, result_class, rows_key, page:, per:)
+      noun = self.class::ERROR_NOUN
+      rows, response = get_json_with_headers(list_url(query), noun)
+      raise Error, "#{noun} response was not a JSON array" unless rows.is_a?(Array)
+
+      result_class.new(
+        rows_key => rows,
+        pagination: Pagination.from_headers(response, items: rows, page: page, per: per)
+      ).freeze
+    end
+
+    def resource_url(id, blank_message, query = {})
+      raise Error, blank_message unless id.is_a?(String)
+
+      trimmed = id.strip
+      # A blank id resolves to the index route (bare array, not one record); a bare dot segment
+      # retargets the request at another path. Neither would 404, so both are rejected here.
+      raise Error, blank_message if trimmed.empty? || [".", ".."].include?(trimmed)
+
+      uri = URI.parse("#{api_endpoint}/#{escape_path_segment(trimmed)}")
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    # `until` is a reserved word, so a method taking an `until:` keyword cannot read it by name;
+    # callers pass `binding.local_variable_get(:until)`.
+    def window_params(since, until_)
+      { since: time_param(:since, since), until: time_param(:until, until_) }
+    end
+
+    # Accepts Time, DateTime, Date or an ISO8601 String. Strings go through untouched so the server
+    # stays the one validator. Raises ArgumentError before any request for anything else.
+    def time_param(name, value)
+      case value
+      when nil, String then value
+      when DateTime then utc_iso8601(value.to_time)
+      when Time then utc_iso8601(value)
+      when Date then value.iso8601
+      else
+        raise ArgumentError, "#{name} must be a Time, DateTime, Date or ISO8601 String, got #{value.class}"
+      end
+    end
+
+    private
+
+    # Whole seconds keep the plain form; a fractional instant keeps its microseconds so a window bound
+    # is not silently truncated.
+    def utc_iso8601(time)
+      utc = time.getutc
+      utc.subsec.zero? ? utc.iso8601 : utc.iso8601(6)
+    end
+  end
+end

data/lib/coolhand/read_requests.rb

@@ -6,9 +6,10 @@ require "json"
 require_relative "errors"
 
 module Coolhand
-  # The GET half of {ApiService}, split out to keep that class inside this repo's 200-line budget.
+  # The GET half of {ApiService}, plus the HTTP helpers {WriteRequests} shares, split out to keep
+  # that class inside this repo's 200-line budget.
   #
-  # Reads raise where writes log-and-return-nil, on purpose: a write is instrumentation inline in
+  # Reads raise where the logging writes log-and-return-nil, on purpose: a write is instrumentation inline in
   # the host app's request, while a read's caller must tell a 404 from a timeout from an empty result.
   module ReadRequests
     # 60s is deliberate, not a slip: writes allow 5, but the server bounds each *statement* at 10s
@@ -32,13 +33,7 @@ module Coolhand
 
       response = perform_get(url, noun)
 
-      unless response.is_a?(Net::HTTPSuccess)
-        raise HttpError.new(
-          "#{noun} request failed (#{response.code}): #{format_error_body(response.body)}",
-          status: response.code.to_i,
-          body: retained_error_body(response.body)
-        )
-      end
+      raise_http_error(response, noun) unless response.is_a?(Net::HTTPSuccess)
 
       [parse_json_body(response.body, noun), response]
     end
@@ -47,10 +42,7 @@ module Coolhand
 
     def perform_get(url, noun)
       uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = (uri.scheme == "https")
-      http.open_timeout = READ_OPEN_TIMEOUT
-      http.read_timeout = READ_TIMEOUT
+      http = build_http(uri)
 
       request = Net::HTTP::Get.new(uri.request_uri)
       apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
@@ -62,6 +54,27 @@ module Coolhand
       raise Error, "#{noun} request failed: #{e.message}"
     end
 
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = READ_OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      http
+    end
+
+    def raise_http_error(response, noun)
+      raise HttpError.new(
+        "#{noun} request failed (#{response.code}): #{format_error_body(response.body)}",
+        status: response.code.to_i,
+        body: retained_error_body(response.body)
+      )
+    end
+
+    # Escapes to RFC 3986 unreserved, so an id carrying `/`, `?` or `#` cannot retarget the request.
+    def escape_path_segment(value)
+      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+    end
+
     def retained_error_body(body)
       return body if body.nil? || body.length <= RETAINED_ERROR_BODY_LIMIT
 

data/lib/coolhand/response_warnings.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Prints the `warnings` a Coolhand log response carries, for {ApiService}.
+  #
+  # Warnings come from the response body and are written to the host app's stdout, so they are
+  # untrusted: each is coerced to a string, stripped of control characters and length-capped, and
+  # the number printed per response is bounded.
+  module ResponseWarnings
+    MAX_WARNING_LENGTH = 500
+    MAX_WARNINGS = 5
+
+    protected
+
+    # The server ingests a log normally but ignores a declared workload/template it cannot honour
+    # (e.g. over the public-key cap), and says so here.
+    def log_response_warnings(result)
+      warnings = result.is_a?(Hash) ? Array(result[:warnings]) : []
+      warnings.first(MAX_WARNINGS).each { |warning| log "⚠️ Coolhand: #{sanitize_warning(warning)}" }
+
+      omitted = warnings.size - MAX_WARNINGS
+      log "⚠️ Coolhand: ... and #{omitted} more warning(s) omitted" if omitted.positive?
+    end
+
+    private
+
+    # Control characters and line/paragraph separators are replaced with a space, not dropped: a
+    # newline would forge a log line and ESC starts a terminal escape sequence. Unicode format
+    # characters (bidi overrides, zero-width) are invisible and can reorder or hide text in a
+    # terminal, so they are removed outright.
+    def sanitize_warning(warning)
+      text = warning.to_s.dup.force_encoding("UTF-8").scrub
+      text = text.gsub(/\p{Cf}+/, "").gsub(/[[:cntrl:]\p{Zl}\p{Zp}]+/, " ").strip
+      return text if text.length <= MAX_WARNING_LENGTH
+
+      "#{text[0, MAX_WARNING_LENGTH]}... [truncated]"
+    end
+  end
+end

data/lib/coolhand/template_service.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
-require "uri"
 require_relative "api_service"
 require_relative "pagination"
+require_relative "read_query"
+require_relative "write_requests"
 
 module Coolhand
   # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
   TemplateSearchResult = Struct.new(:templates, :pagination, keyword_init: true)
 
-  # Read-only. Requires the client's **private** key — the public key is write-only here and is
-  # rejected like an invalid one.
+  # Reads templates and upserts them by key. Requires the client's **private** key — the public key is
+  # write-only here and is rejected like an invalid one.
   #
   # Not a port of the MCP `search_templates` tool and does not agree with its `log_count`.
-  # See docs/template-search.md.
+  # See docs/template-search.md and docs/declared_workloads.md.
   class TemplateService < ApiService
+    include ReadQuery
+    include WriteRequests
+
     ERROR_NOUN = "Template"
     BLANK_ID_MESSAGE = "get_template: id must be a non-empty template hashid"
 
@@ -23,54 +27,50 @@ module Coolhand
 
     # Filters, error semantics and server behaviour: docs/template-search.md.
     def search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil,
-      include_system: nil, page: nil, per: nil)
+      include_system: nil, include_metrics: nil, days_back: nil, since: nil, until: nil, page: nil, per: nil)
       query = {
         search: search,
         workload_id: workload_id,
         status: status,
         include_deprecated: include_deprecated,
         include_system: include_system,
+        include_metrics: include_metrics,
+        days_back: days_back,
+        **window_params(since, binding.local_variable_get(:until)),
         page: page,
         per: per
       }.compact
 
-      templates, response = get_json_with_headers(list_url(query), ERROR_NOUN)
-      raise Error, "#{ERROR_NOUN} response was not a JSON array" unless templates.is_a?(Array)
-
-      TemplateSearchResult.new(
-        templates: templates,
-        pagination: Pagination.from_headers(response, items: templates, page: page, per: per)
-      ).freeze
+      fetch_list(query, TemplateSearchResult, :templates, page: page, per: per)
     end
 
     # Adds `user_prompt_pattern` / `system_prompt_pattern`, which the list omits, and unlike the
-    # list reaches deprecated and system templates by id with no opt-in flag.
-    def get_template(id)
-      get_json(resource_url(id), ERROR_NOUN)
+    # list reaches deprecated and system templates by id with no opt-in flag. Carries `metrics`
+    # unless `include_metrics: false`, which also skips the window validation.
+    def get_template(id, include_metrics: nil, days_back: nil, since: nil, until: nil)
+      query = { include_metrics: include_metrics, days_back: days_back,
+                **window_params(since, binding.local_variable_get(:until)) }.compact
+      get_json(resource_url(id, BLANK_ID_MESSAGE, query), ERROR_NOUN)
     end
 
-    private
-
-    def list_url(query)
-      uri = URI.parse(api_endpoint)
-      uri.query = URI.encode_www_form(query) unless query.empty?
-      uri
+    # Creates the template with this `key`, or updates the existing one. The key is immutable; a new
+    # `name` renames the display name. `workload` (`{ id: }` or `{ key: }`, the latter find-or-created)
+    # is needed only when the template is new; an existing one keeps its workload. Returns the template
+    # Hash. Raises {Coolhand::HttpError} on a non-2xx response. See docs/declared_workloads.md.
+    def upsert(key:, workload: nil, name: nil, reporter: nil)
+      body = { name: name, reporter: reporter, **workload_params(workload) }.compact
+      request_json(:put, by_key_url("upsert", key), ERROR_NOUN, body: body)
     end
 
-    def resource_url(id)
-      raise Error, BLANK_ID_MESSAGE unless id.is_a?(String)
-
-      trimmed = id.strip
-      # A blank id resolves to the index route (bare array, not one template); a bare dot segment
-      # retargets the request at another path. Neither would 404, so both are rejected here.
-      raise Error, BLANK_ID_MESSAGE if trimmed.empty? || [".", ".."].include?(trimmed)
+    private
 
-      URI.parse("#{api_endpoint}/#{escape_path_segment(trimmed)}")
-    end
+    def workload_params(workload)
+      return {} if workload.nil?
+      unless workload.is_a?(Hash)
+        raise ArgumentError, "upsert: workload must be a Hash with :id or :key, got #{workload.class}"
+      end
 
-    # Escapes to RFC 3986 unreserved, so an id carrying `/`, `?` or `#` cannot retarget the request.
-    def escape_path_segment(value)
-      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+      { workload_id: workload[:id] || workload["id"], workload_key: workload[:key] || workload["key"] }
     end
   end
 end

data/lib/coolhand/version.rb

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

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -31,7 +31,7 @@ module Coolhand
         when "JOB_STATE_PENDING", "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
           Rails.logger.info("[Interceptor] Vertex batch #{batch_info} still processing")
         when "JOB_STATE_SUCCEEDED"
-          process_completed_batch(batch_results)
+          LogQueue.submit(lane: :batch) { process_completed_batch_logging_errors(batch_results) }
         when "JOB_STATE_FAILED"
           handle_failed_batch
         else
@@ -43,6 +43,14 @@ module Coolhand
 
       private
 
+      # Runs on the batch lane's worker thread, where an escaping error would only reach
+      # Coolhand.log (silenceable) rather than the Rails log `call` reports to.
+      def process_completed_batch_logging_errors(batch_results)
+        process_completed_batch(batch_results)
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to process Vertex batch results for #{batch_info}: #{e.message}")
+      end
+
       def process_completed_batch(batch_results)
         name = batch_info["name"].to_s.sub(%r{\A/+}, "")
         unless name.match?(VALID_NAME_PATTERN)