coolhand 0.6.0 → 0.8.0

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.6.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,11 +90,22 @@ 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
 
       puts "COOLHAND: #{message}"
+    rescue StandardError
+      # Logging must never raise into the host app (e.g. a closed stdout) — least of all from
+      # the interceptor's ensure block, where it would replace the host's own response.
+      nil
     end
 
     # Creates a new FeedbackService instance
@@ -109,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.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-13 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: