coolhand 0.8.0 → 0.10.0

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

@@ -3,18 +3,20 @@
 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"
@@ -39,13 +41,7 @@ module Coolhand
         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
@@ -56,5 +52,25 @@ module Coolhand
                 **window_params(since, binding.local_variable_get(:until)) }.compact
       get_json(resource_url(id, BLANK_ID_MESSAGE, query), ERROR_NOUN)
     end
+
+    # 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
+
+    private
+
+    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
+
+      { 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.8.0"
+  VERSION = "0.10.0"
 end

data/lib/coolhand/workload_service.rb

@@ -3,15 +3,17 @@
 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.
   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.
+  # Lists workloads and upserts them by key. Requires the client's **private** key. There is no per-id
+  # endpoint. See docs/workload-search.md and docs/declared_workloads.md.
   class WorkloadService < ApiService
     include ReadQuery
+    include WriteRequests
 
     ERROR_NOUN = "Workload"
 
@@ -34,13 +36,15 @@ module Coolhand
         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)
+      fetch_list(query, WorkloadSearchResult, :workloads, page: page, per: per)
+    end
 
-      WorkloadSearchResult.new(
-        workloads: workloads,
-        pagination: Pagination.from_headers(response, items: workloads, page: page, per: per)
-      ).freeze
+    # Creates the workload with this `key`, or updates the existing one. The key is immutable; a new
+    # `name` renames the display name. Returns the workload Hash (the server answers 201 on create,
+    # 200 on update). Raises {Coolhand::HttpError} on a non-2xx response. See docs/declared_workloads.md.
+    def upsert(key:, name: nil, description: nil, reporter: nil)
+      body = { name: name, description: description, reporter: reporter }.compact
+      request_json(:put, by_key_url("upsert", key), ERROR_NOUN, body: body)
     end
   end
 end

data/lib/coolhand/write_requests.rb

@@ -13,6 +13,8 @@ module Coolhand
   # `api_key`, `apply_headers` and `format_error_body` from there and the shared HTTP helpers from
   # {ReadRequests}.
   module WriteRequests
+    DOT_SEGMENTS = [".", ".."].freeze
+
     protected
 
     # Returns the parsed body, or nil for an empty one (204).
@@ -26,6 +28,18 @@ module Coolhand
       response.body.to_s.strip.empty? ? nil : parse_json_body(response.body, noun)
     end
 
+    # `<endpoint>/by_key/<key>` for the upsert routes, which are globs: a key like "Parser#call/squish:L2"
+    # keeps its slashes and each segment is escaped, so `#` or `?` in a key cannot retarget the request.
+    def by_key_url(method_name, key)
+      trimmed = key.is_a?(String) ? key.strip : ""
+      segments = trimmed.split("/", -1)
+      if trimmed.empty? || segments.any? { |segment| segment.empty? || DOT_SEGMENTS.include?(segment) }
+        raise Error, "#{method_name}: key must be a non-empty string without empty or dot path segments"
+      end
+
+      URI.parse("#{api_endpoint}/by_key/#{segments.map { |segment| escape_path_segment(segment) }.join('/')}")
+    end
+
     private
 
     def perform_write(verb, url, noun, body)

data/lib/coolhand.rb

@@ -10,6 +10,9 @@ require_relative "coolhand/errors"
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"
 require_relative "coolhand/collector"
+require_relative "coolhand/declared_context"
+require_relative "coolhand/declarable"
+require_relative "coolhand/rails_auto_declare"
 require_relative "coolhand/log_queue"
 require_relative "coolhand/base_interceptor"
 require_relative "coolhand/net_http_interceptor"
@@ -19,8 +22,11 @@ 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/public_content_service"
 require_relative "coolhand/log_service"
 require_relative "coolhand/webhook_interceptor"
+# Only when Rails is already loaded; the gem has no Rails dependency.
+require_relative "coolhand/railtie" if defined?(Rails::Railtie)
 
 # The main module for the Coolhand gem.
 # It provides the configuration interface and initializes the patching.
@@ -35,6 +41,7 @@ module Coolhand
     def reset_configuration!
       @configuration = Configuration.new
       Thread.current[:coolhand_capture_override] = nil
+      DeclaredContext.clear!
     end
 
     # Provides a block to configure the gem.
@@ -74,20 +81,25 @@ module Coolhand
       end
     end
 
-    def without_capture
-      previous = Thread.current[:coolhand_capture_override]
-      Thread.current[:coolhand_capture_override] = false
-      yield
-    ensure
-      Thread.current[:coolhand_capture_override] = previous
+    def without_capture(&block)
+      override_capture(false, &block)
     end
 
-    def with_capture
-      previous = Thread.current[:coolhand_capture_override]
-      Thread.current[:coolhand_capture_override] = true
-      yield
-    ensure
-      Thread.current[:coolhand_capture_override] = previous
+    def with_capture(&block)
+      override_capture(true, &block)
+    end
+
+    # Declares the workload/template that LLM calls captured inside the block belong to. Nested
+    # blocks override per field (`reporter`, `workload`, `template`), innermost wins. `workload` and
+    # `template` are Hashes with `id:` (an existing record) or `key:` (find-or-created), plus optional
+    # `name:` (and `description:` on a workload). See docs/declared_workloads.md.
+    #
+    # Example:
+    #   Coolhand.with_context(reporter: "squishling", workload: { key: "Parser#call" }) { client.chat(...) }
+    def with_context(reporter: nil, workload: nil, template: nil, &block)
+      raise ArgumentError, "Coolhand.with_context requires a block" unless block
+
+      DeclaredContext.with(reporter: reporter, workload: workload, template: template, &block)
     end
 
     # Blocks until log requests queued by async logging have been sent, or the timeout (in
@@ -136,6 +148,12 @@ module Coolhand
       LogService.new
     end
 
+    # Creates a new PublicContentService, for reading the Coolhand help center. Needs no API key; a
+    # configured one is sent and lifts the anonymous rate limit.
+    def public_content_service
+      PublicContentService.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
@@ -149,5 +167,16 @@ module Coolhand
 
       true
     end
+
+    private
+
+    # Forces capture on or off for the block on this thread, restoring the previous override after.
+    def override_capture(enabled)
+      previous = Thread.current[:coolhand_capture_override]
+      Thread.current[:coolhand_capture_override] = enabled
+      yield
+    ensure
+      Thread.current[:coolhand_capture_override] = previous
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -47,9 +47,11 @@ files:
 - SECURITY.md
 - docs/anthropic.md
 - docs/configuration.md
+- docs/declared_workloads.md
 - docs/elevenlabs.md
 - docs/feedback-links.md
 - docs/feedback.md
+- docs/help-center.md
 - docs/log-search.md
 - docs/openai.md
 - docs/template-search.md
@@ -60,6 +62,8 @@ files:
 - lib/coolhand/base_interceptor.rb
 - lib/coolhand/collector.rb
 - lib/coolhand/configuration.rb
+- lib/coolhand/declarable.rb
+- lib/coolhand/declared_context.rb
 - lib/coolhand/default_exclude_api_patterns.yml
 - lib/coolhand/default_intercept_addresses.yml
 - lib/coolhand/default_intercept_path_patterns.yml
@@ -74,8 +78,12 @@ files:
 - lib/coolhand/open_ai/webhook_validator.rb
 - lib/coolhand/optimization_feedback_link_service.rb
 - lib/coolhand/pagination.rb
+- lib/coolhand/public_content_service.rb
+- lib/coolhand/rails_auto_declare.rb
+- lib/coolhand/railtie.rb
 - lib/coolhand/read_query.rb
 - lib/coolhand/read_requests.rb
+- lib/coolhand/response_warnings.rb
 - lib/coolhand/template_service.rb
 - lib/coolhand/version.rb
 - lib/coolhand/vertex/batch_result_processor.rb