coolhand 0.5.0 → 0.6.0

data/lib/coolhand/template_service.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "api_service"
+require_relative "pagination"
+
+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.
+  #
+  # 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
+    ERROR_NOUN = "Template"
+    BLANK_ID_MESSAGE = "get_template: id must be a non-empty template hashid"
+
+    def initialize
+      super("v2/llm_request_templates")
+    end
+
+    # 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)
+      query = {
+        search: search,
+        workload_id: workload_id,
+        status: status,
+        include_deprecated: include_deprecated,
+        include_system: include_system,
+        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
+    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\-._~]/)
+    end
+  end
+end

data/lib/coolhand/version.rb

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

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "../../coolhand"
+
 module Coolhand
   module Vertex
     class BatchResultProcessor
-      attr_reader :batch_info
+      # Global endpoint, not the job's region-specific one — matches the
+      # "aiplatform.googleapis.com" entry in default_intercept_addresses.yml
+      # so backend URL-shape classification stays consistent with the rest
+      # of the gem's Vertex traffic. The URL this produces always contains
+      # "/batchPredictionJobs/", which is also the default client-side
+      # exclude_api_patterns entry — that's harmless here since this class
+      # sends via BaseInterceptor/ApiService directly and never goes through
+      # NetHttpInterceptor's intercept/exclude filtering.
+      VERTEX_API_BASE_URL = "https://aiplatform.googleapis.com/v1/"
+      SOURCE_API = "vertex"
+      VALID_NAME_PATTERN = %r{\Aprojects/[^/?#\s]+/locations/[^/?#\s]+/batchPredictionJobs/[^/?#\s]+\z}
+
+      attr_reader :batch_info, :model
 
-      def initialize(batch_info:)
+      def initialize(batch_info:, model: nil)
         @batch_info = batch_info
+        @model = model
       end
 
       def call(batch_results = [])
@@ -16,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"
-          batch_results.each { |batch_item| process_completed_batch(batch_item) }
+          process_completed_batch(batch_results)
         when "JOB_STATE_FAILED"
           handle_failed_batch
         else
@@ -28,56 +43,98 @@ module Coolhand
 
       private
 
-      def process_completed_batch(batch_item)
-        send_complete_request_log(request_id: SecureRandom.hex(16),
+      def process_completed_batch(batch_results)
+        name = batch_info["name"].to_s.sub(%r{\A/+}, "")
+        unless name.match?(VALID_NAME_PATTERN)
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a missing or " \
+                             "invalid job resource name (#{batch_info['name'].inspect}); skipping request log")
+          return
+        end
+
+        begin
+          start_time = Time.iso8601(batch_info["startTime"])
+          end_time   = Time.iso8601(batch_info["endTime"])
+        rescue TypeError, ArgumentError
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a missing or " \
+                             "invalid startTime/endTime; skipping request log")
+          return
+        end
+
+        if end_time < start_time
+          Rails.logger.warn("[Interceptor] Vertex batch #{batch_info['displayName']} has an endTime before " \
+                            "its startTime; sending request log(s) with duration_ms clamped to 0")
+          end_time = start_time
+        end
+
+        duration_ms = ((end_time - start_time) * 1000).to_i
+        url = "#{VERTEX_API_BASE_URL}#{name}"
+        resolved = resolved_model
+
+        sent = batch_results.count do |batch_item|
+          send_item_log(batch_item, url: url, model: resolved, start_time: start_time, end_time: end_time,
+            duration_ms: duration_ms)
+        end
+
+        # "Sent" here means dispatched to BaseInterceptor without a local
+        # error (e.g. a malformed batch_item) — BaseInterceptor swallows any
+        # downstream delivery failure itself, so this can't confirm the
+        # Coolhand API actually received the log.
+        if sent == batch_results.size
+          Rails.logger.info("[Interceptor] Dispatched #{sent} result(s) for Vertex batch " \
+                            "#{batch_info['displayName']} for logging")
+        else
+          Rails.logger.warn("[Interceptor] Dispatched #{sent}/#{batch_results.size} result(s) for Vertex " \
+                            "batch #{batch_info['displayName']} for logging — " \
+                            "#{batch_results.size - sent} item(s) were malformed and skipped")
+        end
+      end
+
+      def send_item_log(batch_item, url:, model:, start_time:, end_time:, duration_ms:)
+        unless batch_item.is_a?(Hash) && (batch_item.key?("request") || batch_item.key?("response"))
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a malformed result " \
+                             "item (#{batch_item.class}); skipping request log")
+          return false
+        end
+
+        BaseInterceptor.send_complete_request_log(
+          request_id: SecureRandom.hex(16),
           method: "POST",
-          url: batch_info["name"],
+          url: url,
+          source_api: SOURCE_API,
+          model: model,
+          request_headers: {},
           request_body: batch_item["request"],
+          response_headers: {},
           response_body: batch_item["response"],
           status_code: 200,
-          start_time: batch_info["startTime"],
-          end_time: batch_info["endTime"])
-
-        Rails.logger.info("[Interceptor] Successfully processed Vertex batch #{batch_info['displayName']}")
+          start_time: start_time,
+          end_time: end_time,
+          duration_ms: duration_ms,
+          is_streaming: false
+        )
+        true
       rescue StandardError => e
         Rails.logger.error("[Interceptor] Failed to send request log: #{e.message}")
+        false
       end
 
-      def send_complete_request_log(request_id:, method:, url:, request_body:, response_body:, status_code:,
-        start_time:, end_time:)
-        start_time = Time.iso8601(start_time)
-        end_time   = Time.iso8601(end_time)
-        duration_ms = ((end_time - start_time) * 1000).to_i
+      def resolved_model
+        candidate = [model, batch_info["model"]].find { |c| Coolhand.required_field?(c) }&.to_s&.strip
+        return if candidate.nil?
 
-        request_data = {
-          raw_request: {
-            id: request_id,
-            timestamp: start_time,
-            method: method.to_s.downcase,
-            url: url,
-            headers: {},
-            request_body: request_body,
-            response_headers: {},
-            response_body: response_body,
-            status_code: status_code,
-            duration_ms: duration_ms,
-            completed_at: end_time,
-            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}"
+        # Only normalize genuine Vertex model resource paths (e.g.
+        # "publishers/google/models/gemini-2.0-flash" or
+        # "projects/P/locations/L/models/M@1") down to their bare id. A
+        # caller-supplied `model:` might itself be a provider-qualified slug
+        # that happens to contain a slash (e.g. "meta-llama/Llama-3") —
+        # leave anything that isn't a resource path untouched.
+        candidate.match?(%r{\A(publishers|projects)/}) ? candidate.split("/").last : candidate
       end
 
       # TODO: implement API to handle failed batch results and display errors on dashboard page
       def handle_failed_batch
-        Rails.logger.error("[Interceptor] Vertex batch for #{batch_info['displayName']} " \
-                           "failed: #{batch_info['error']['message']}")
+        message = batch_info["error"].is_a?(Hash) ? batch_info["error"]["message"] : batch_info["error"]
+        Rails.logger.error("[Interceptor] Vertex batch for #{batch_info['displayName']} failed: #{message}")
       end
     end
   end

data/lib/coolhand/webhook_interceptor.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "open_ai/webhook_validator"
+require_relative "open_ai/batch_result_processor"
+
 module Coolhand
   module WebhookInterceptor
     def intercept_batch_request
@@ -14,10 +17,18 @@ module Coolhand
       end
 
       payload = JSON.parse(@validator.payload)
+      raise TypeError, "webhook payload must be a JSON object, got #{payload.class}" unless payload.is_a?(Hash)
 
       process_event(payload)
     rescue StandardError => e
+      # Fail closed: any error here (malformed payload, a bug in
+      # process_event/BatchResultProcessor, etc.) must still halt the
+      # before_action chain. Falling through without calling `head` would
+      # let the controller action run for a request whose webhook
+      # signature was never confirmed valid.
       Rails.logger.error("[Interceptor] Failed to intercept batch request: #{e.message}")
+      head :unauthorized
+      false
     end
 
     def webhook_secret

data/lib/coolhand.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "uri"
-require "faraday"
 require "securerandom"
 require "json"
 require "base64"
+require "time"
 
+require_relative "coolhand/errors"
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"
 require_relative "coolhand/collector"
@@ -14,13 +15,12 @@ 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/webhook_interceptor"
 
 # The main module for the Coolhand gem.
 # It provides the configuration interface and initializes the patching.
 module Coolhand
-  class Error < StandardError; end
-
   # Class-level instance variables to hold the configuration
   @configuration = Configuration.new
 
@@ -62,12 +62,11 @@ module Coolhand
 
       return yield unless configuration.enabled
 
-      patched = NetHttpInterceptor.patched?
       NetHttpInterceptor.patch!
       begin
         yield
       ensure
-        NetHttpInterceptor.unpatch! unless patched
+        NetHttpInterceptor.unpatch!
       end
     end
 
@@ -104,6 +103,12 @@ module Coolhand
       LoggerService.new
     end
 
+    # Creates a new TemplateService instance, for reading LLM request templates back out of
+    # Coolhand. Needs the private API key - the public key is write-only on this API.
+    def template_service
+      TemplateService.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.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -26,23 +26,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.2'
 description: Automatically intercept and log LLM requests from Ruby applications.
-  Supports OpenAI, official Anthropic gem, ruby-anthropic gem, and other Faraday-based
-  libraries. Features dual interceptor architecture, streaming support, thread-safe
-  operation, and automatic duplicate request prevention.
+  Supports OpenAI, official Anthropic gem, ruby-anthropic gem, Google Gemini, Google
+  Vertex AI, AWS Bedrock, OpenRouter, and any other library using Net::HTTP (directly,
+  or via Faraday's default adapter). Features a single unified Net::HTTP interceptor,
+  streaming support, thread-safe operation, and automatic duplicate request prevention.
 email:
 - mc@coolhandlabs.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/skills/loop-review/SKILL.md"
-- ".claude/skills/prep-release/SKILL.md"
-- ".idea/coolhand-ruby.iml"
 - ".rspec"
 - ".rubocop.yml"
 - ".simplecov"
+- AGENTS.harness.md
 - CHANGELOG.md
-- CLAUDE.md
 - LICENSE
 - README.md
 - Rakefile
@@ -51,6 +49,9 @@ files:
 - docs/configuration.md
 - docs/elevenlabs.md
 - docs/feedback.md
+- docs/openai.md
+- docs/template-search.md
+- docs/vertex.md
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
 - lib/coolhand/base_interceptor.rb
@@ -58,11 +59,17 @@ files:
 - lib/coolhand/configuration.rb
 - lib/coolhand/default_exclude_api_patterns.yml
 - lib/coolhand/default_intercept_addresses.yml
+- lib/coolhand/default_intercept_path_patterns.yml
+- lib/coolhand/errors.rb
 - lib/coolhand/feedback_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/pagination.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

data/.claude/skills/loop-review/SKILL.md

@@ -1,112 +0,0 @@
----
-name: loop-review
-description: |
-  Iteratively runs code review against the current diff, applies fixes, and
-  re-reviews until a round comes back clean (or a safety cap is hit). Use
-  when the user types /loop-review, asks to "loop the review", "review
-  until clean", "keep reviewing and fixing until nothing's left", or wants
-  a self-healing code review cycle instead of a single one-shot pass.
-user_invocable: true
-version: 0.3.0
----
-
-# Loop Review
-
-This skill runs `/code-review` repeatedly against the working diff, applies
-fixes between rounds, and re-reviews until a round finds nothing new or a
-safety cap is reached. Use it after a merge, a large diff, or whenever a
-single review pass isn't enough to converge on a clean state.
-
-## Scope
-
-Default scope is the diff between the current branch and its merge-base
-with the repo's base branch (`git diff $(git merge-base origin/main
-HEAD)...HEAD`, or `origin/main` substituted with whatever base branch
-applies). If `$ARGUMENTS` names a path or a narrower scope, review only
-that instead of the full diff.
-
-This skill is deliberately diff-scoped. For a whole-package audit before a
-release (full-codebase security red-team, docs review, everything since
-the last tag) use `/prep-release` instead.
-
-`$ARGUMENTS` may also contain:
-- An effort level to pass through to `/code-review` (`low`/`medium`/
-  `high`/`high→max`/`ultra`). Default: `medium`.
-- A round cap override, e.g. `--max-rounds 3`. Default: 5.
-
-## The round loop
-
-1. Invoke `/code-review <effort> --fix` (via the `Skill` tool) against the
-   current scope.
-2. **Dry round (0 findings) → converged.** Stop and move to verification.
-3. **Findings found and fixed** → do not declare victory yet. Run another
-   round to confirm the fixes didn't introduce a regression and that
-   nothing was missed.
-4. **No-progress detection**: if two consecutive rounds return the same
-   non-empty set of findings, `--fix` isn't resolving them mechanically
-   (likely a design/architecture call that needs a human). Stop looping,
-   list the stuck findings, and hand them to the user instead of retrying
-   forever.
-5. **Safety cap**: if the round cap is reached without converging or
-   getting stuck, stop and report the remaining findings — don't loop
-   silently past the cap.
-
-Each round's fixes should stay reviewable: don't squash multiple rounds
-into one silent edit. Note per-round changes in the final summary so the
-user can inspect them with `git diff`.
-
-## Review criteria
-
-Beyond whatever `/code-review` already checks for correctness bugs and
-reuse/simplification/efficiency, every round in a Ruby gem repo like this
-one should also flag:
-
-- **Ruby idiom / DRY**: semantic, expressive naming; no duplicated logic
-  that should be extracted into a shared method; idiomatic use of
-  Ruby/Enumerable over manual loops where it reads better; no needless
-  boilerplate.
-- **Gem publishing discipline**: don't break public interfaces unless
-  necessary.
-  - If a break is necessary, it must come with: a `CHANGELOG.md` entry in
-    Keep a Changelog format (this repo already follows that format — match
-    the style of existing entries, e.g. plain-English migration notes like
-    the `0.5.0` entry) and a version bump in `lib/coolhand/version.rb` that
-    matches SemVer (patch = fix, minor = backward-compatible addition,
-    minor = breaking change while pre-1.0, consistent with this repo's own
-    versioning history).
-  - Check the optional-provider-dependency rule from this repo's
-    `CLAUDE.md`: provider SDK `require`s (`openai`, `anthropic`,
-    `google-generativeai`, etc.) must stay scoped to the file that uses
-    them and lazy-loaded, never added to `lib/coolhand.rb` or the gemspec
-    as a hard dependency.
-- **Security**: injection risks, unsafe deserialization, secrets or
-  credentials logged or committed, unvalidated input crossing a trust
-  boundary, and anything touching how API keys/tokens are handled,
-  stored, or transmitted.
-
-## Post-loop verification
-
-Once the loop converges (or stops early per the rules above), run the
-project's lint/test command and include the result in the final summary.
-For this repo that's `bundle exec rake` (runs `rspec` then `rubocop`, per
-the `Rakefile`). If a fix round changed something outside this repo's
-usual toolchain, discover the right command instead of assuming.
-
-## Rationalizations to resist
-
-- *"The first round already looked clean, I don't need a confirming
-  round."* A fix round can introduce its own regression. Always re-review
-  after applying fixes before declaring convergence.
-- *"Rubocop passed, so the review is done."* Lint passing is not the same
-  as the review being clean — lint doesn't check the criteria above
-  (interface breakage, changelog/version discipline, security). Run both.
-- *"This finding keeps coming back, I'll just keep re-running --fix and
-  it'll eventually take."* If the same non-empty finding set repeats
-  across two rounds, `--fix` isn't going to resolve it. Stop and surface
-  it — looping past that point just burns rounds for no gain.
-
-## Safety
-
-- Never force-push or amend existing commits as part of this loop.
-- The skill only edits the working tree; committing and pushing stays with
-  the user.