coolhand 0.7.0 → 0.8.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/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/read_query.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "uri"
+require_relative "errors"
+
+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
+
+    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/template_service.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "uri"
 require_relative "api_service"
 require_relative "pagination"
+require_relative "read_query"
 
 module Coolhand
   # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
@@ -14,6 +14,8 @@ module Coolhand
   # Not a port of the MCP `search_templates` tool and does not agree with its `log_count`.
   # See docs/template-search.md.
   class TemplateService < ApiService
+    include ReadQuery
+
     ERROR_NOUN = "Template"
     BLANK_ID_MESSAGE = "get_template: id must be a non-empty template hashid"
 
@@ -23,13 +25,16 @@ 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
@@ -44,33 +49,12 @@ module Coolhand
     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)
-    end
-
-    private
-
-    def list_url(query)
-      uri = URI.parse(api_endpoint)
-      uri.query = URI.encode_www_form(query) unless query.empty?
-      uri
-    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)
-
-      URI.parse("#{api_endpoint}/#{escape_path_segment(trimmed)}")
-    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\-._~]/)
+    # 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
   end
 end

data/lib/coolhand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coolhand
-  VERSION = "0.7.0"
+  VERSION = "0.8.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)

data/lib/coolhand/workload_service.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+require_relative "pagination"
+require_relative "read_query"
+
+module Coolhand
+  # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
+  WorkloadSearchResult = Struct.new(:workloads, :pagination, keyword_init: true)
+
+  # Read-only. Requires the client's **private** key. There is no per-id endpoint.
+  # See docs/workload-search.md.
+  class WorkloadService < ApiService
+    include ReadQuery
+
+    ERROR_NOUN = "Workload"
+
+    def initialize
+      super("v2/workloads")
+    end
+
+    # Filters, windows, error semantics and server behaviour: docs/workload-search.md.
+    def search_workloads(search: nil, include_archived: nil, include_system: nil, include_templates: nil,
+      include_metrics: nil, days_back: nil, since: nil, until: nil, page: nil, per: nil)
+      query = {
+        search: search,
+        include_archived: include_archived,
+        include_system: include_system,
+        include_templates: include_templates,
+        include_metrics: include_metrics,
+        days_back: days_back,
+        **window_params(since, binding.local_variable_get(:until)),
+        page: page,
+        per: per
+      }.compact
+
+      workloads, response = get_json_with_headers(list_url(query), ERROR_NOUN)
+      raise Error, "#{ERROR_NOUN} response was not a JSON array" unless workloads.is_a?(Array)
+
+      WorkloadSearchResult.new(
+        workloads: workloads,
+        pagination: Pagination.from_headers(response, items: workloads, page: page, per: per)
+      ).freeze
+    end
+  end
+end

data/lib/coolhand/write_requests.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "errors"
+require_relative "read_requests"
+
+module Coolhand
+  # POST/DELETE counterpart of {ReadRequests} for callers that act on the response: raises on any
+  # failure where {ApiService#send_request} logs and returns nil. Timeouts are the read ones, for
+  # the same server-side statement-bound reason. Mix into an {ApiService} subclass: it relies on
+  # `api_key`, `apply_headers` and `format_error_body` from there and the shared HTTP helpers from
+  # {ReadRequests}.
+  module WriteRequests
+    protected
+
+    # Returns the parsed body, or nil for an empty one (204).
+    def request_json(verb, url, noun, body: nil)
+      raise Error, "#{noun} request failed: an API key is required" unless Coolhand.required_field?(api_key)
+
+      response = perform_write(verb, url, noun, body)
+
+      raise_http_error(response, noun) unless response.is_a?(Net::HTTPSuccess)
+
+      response.body.to_s.strip.empty? ? nil : parse_json_body(response.body, noun)
+    end
+
+    private
+
+    def perform_write(verb, url, noun, body)
+      uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+      http = build_http(uri)
+
+      request = Net::HTTP.const_get(verb.to_s.capitalize).new(uri.request_uri)
+      apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
+      unless body.nil?
+        apply_headers(request, "Content-Type" => "application/json")
+        request.body = JSON.generate(body).force_encoding("UTF-8")
+      end
+
+      Coolhand.without_capture { http.request(request) }
+    rescue StandardError => e
+      raise Error, "#{noun} request failed: #{e.message}"
+    end
+  end
+end

data/lib/coolhand.rb

@@ -10,12 +10,16 @@ require_relative "coolhand/errors"
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"
 require_relative "coolhand/collector"
+require_relative "coolhand/log_queue"
 require_relative "coolhand/base_interceptor"
 require_relative "coolhand/net_http_interceptor"
 require_relative "coolhand/api_service"
 require_relative "coolhand/logger_service"
 require_relative "coolhand/feedback_service"
 require_relative "coolhand/template_service"
+require_relative "coolhand/optimization_feedback_link_service"
+require_relative "coolhand/workload_service"
+require_relative "coolhand/log_service"
 require_relative "coolhand/webhook_interceptor"
 
 # The main module for the Coolhand gem.
@@ -86,6 +90,13 @@ module Coolhand
       Thread.current[:coolhand_capture_override] = previous
     end
 
+    # Blocks until log requests queued by async logging have been sent, or the timeout (in
+    # seconds) elapses. Returns true if everything was sent. Pending logs are also flushed
+    # automatically at process exit.
+    def flush(timeout: LogQueue::DEFAULT_FLUSH_TIMEOUT)
+      LogQueue.flush(timeout)
+    end
+
     # A simple logger that respects the 'silent' configuration option.
     def log(message)
       return if configuration.silent
@@ -113,6 +124,24 @@ module Coolhand
       TemplateService.new
     end
 
+    # Creates a new WorkloadService instance, for listing workloads (with optional cost and
+    # performance metrics). Needs the private API key.
+    def workload_service
+      WorkloadService.new
+    end
+
+    # Creates a new LogService instance, for reading logs back out of Coolhand. Distinct from
+    # {logger_service}, which writes them. Needs the private API key.
+    def log_service
+      LogService.new
+    end
+
+    # Creates a new OptimizationFeedbackLinkService instance, for linking feedback to an
+    # optimization as evidence. Needs the private API key.
+    def optimization_feedback_link_service
+      OptimizationFeedbackLinkService.new
+    end
+
     def required_field?(value)
       return false if value.nil?
       return false if value.respond_to?(:empty?) && value.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -48,10 +48,13 @@ files:
 - docs/anthropic.md
 - docs/configuration.md
 - docs/elevenlabs.md
+- docs/feedback-links.md
 - docs/feedback.md
+- docs/log-search.md
 - docs/openai.md
 - docs/template-search.md
 - docs/vertex.md
+- docs/workload-search.md
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
 - lib/coolhand/base_interceptor.rb
@@ -62,17 +65,23 @@ files:
 - lib/coolhand/default_intercept_path_patterns.yml
 - lib/coolhand/errors.rb
 - lib/coolhand/feedback_service.rb
+- lib/coolhand/log_queue.rb
+- lib/coolhand/log_service.rb
 - lib/coolhand/logger_service.rb
 - lib/coolhand/net_http_interceptor.rb
 - lib/coolhand/open_ai/batch_result_processor.rb
 - lib/coolhand/open_ai/webhook_id_store.rb
 - lib/coolhand/open_ai/webhook_validator.rb
+- lib/coolhand/optimization_feedback_link_service.rb
 - lib/coolhand/pagination.rb
+- lib/coolhand/read_query.rb
 - lib/coolhand/read_requests.rb
 - lib/coolhand/template_service.rb
 - lib/coolhand/version.rb
 - lib/coolhand/vertex/batch_result_processor.rb
 - lib/coolhand/webhook_interceptor.rb
+- lib/coolhand/workload_service.rb
+- lib/coolhand/write_requests.rb
 - sig/coolhand/ruby.rbs
 homepage: https://coolhandlabs.com/
 licenses: