coolhand 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 256c9237619b3f7116aa9751f78f0d0e367381b12afa694742da07ed1d7d3123
-  data.tar.gz: 149ddf8c4cd1800b105382ade5d2a2e9e57a360884e34e1b988b926739e90f30
+  metadata.gz: 48857d802183f91a163c82c3e1dd89ce34ac7a8f1f3d1079c5ae6d5d594ad300
+  data.tar.gz: a852465d5b9dced73580eff8c81f45093a97c48c79a66579cff27c2dbedc7cbe
 SHA512:
-  metadata.gz: 2ccbf54c2787a8df93178120583d83666553454a1b86385ec1c4ea10e228b859b995a35bed1450e9ab6d38dbb5d145d9b7a269be89f5562870d51a63630e5653
-  data.tar.gz: 4e6db88c4530737370030809a9d8e094d791761a6306a63701edc4413ed81f61a716d975953799c3d46b0cebbb3ddd9e1d172b22ee5d7b29c18bdd65ffe9e25c
+  metadata.gz: 0d4e6bc5e9ef29365afaba5b9c4a4edbadb552f77268adfe27ac6276f23cd44e4c75fe6df85b1ddef8bdf25d99d88204a46a127dcce7c3a2183edc09e5019508
+  data.tar.gz: ee192c55d280b47abc3f6a9af7f2ddd48d4966493955cee5614557feeea2d87d71a28c16f488fee4dc9fddd916b88fc9ee98621e058e3ad0de80431fc6bd871c

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-18
+
+### Added
+- **Declare the workload and template of captured LLM calls** ([#153](https://github.com/Coolhand-Labs/coolhand-ruby/pull/153)) — `Coolhand.with_context(reporter:, workload:, template:) { ... }` stamps every LLM call captured inside the block with the workload and template it belongs to, sent as `llm_request_log.declared`. The context is snapshotted on the calling thread, so it survives `async_logging`. Nested blocks override per field (innermost wins). `Coolhand::Declarable` (`coolhand_workload`, `coolhand_declare`, `coolhand_declare_all`) declares it once on a class, inherited by subclasses, and opt-in `config.auto_declare = [:active_job, :controller]` does the same for Rails jobs and controller actions (the gem still has no Rails dependency). `Coolhand.workload_service.upsert` and `Coolhand.template_service.upsert` create or update records by key with your **private** API key and raise `Coolhand::HttpError` on failure, and `warnings` returned with a logged request (e.g. the public-key cap) are now logged. Keys longer than 255 characters, with surrounding whitespace or a leading, trailing or doubled `/`, and a template `key` with no workload raise `ArgumentError` up front, because the server would reject and drop the whole log. Older servers ignore `declared`. See [Declared Workloads](docs/declared_workloads.md).
+- `bin/live-examples` (also `bundle exec rake examples:live`) runs every `examples/*.rb` against real provider keys and prints one `PASS` / `SKIP` / `FAIL` line per script ([#155](https://github.com/Coolhand-Labs/coolhand-ruby/pull/155)). Development tooling only: `bin/` and `examples/` are not packaged in the gem. See [Examples](examples/README.md).
+
+### Changed
+- The `🔗 Net::HTTP interceptor patched` log line is no longer printed when the interceptor is installed ([#154](https://github.com/Coolhand-Labs/coolhand-ruby/pull/154)). **Migration note:** anything that matched on that line in log output should stop doing so; use `Coolhand::NetHttpInterceptor.patched?` instead.
+- Internal de-duplication with no behavior change ([#156](https://github.com/Coolhand-Labs/coolhand-ruby/pull/156)): list reads share `ReadQuery#fetch_list`, `LoggerService` shares one webhook-rejection path, `OpenAi::WebhookValidator` shares one enforce-or-allow path (same error messages and same strict/lenient behavior by `Rails.env`), and `Coolhand.with_capture` / `without_capture` share one override helper. `contract/` (declared, intentional duplication) is excluded from the gem package.
+- CI: added the `exhale` duplication and complexity gate ([#156](https://github.com/Coolhand-Labs/coolhand-ruby/pull/156)), and bumped `ruby/setup-ruby` to 1.329.0 ([#150](https://github.com/Coolhand-Labs/coolhand-ruby/pull/150)) and `actions/upload-artifact` to 7.0.2 ([#151](https://github.com/Coolhand-Labs/coolhand-ruby/pull/151)).
+
+### Fixed
+- `OpenAi::WebhookValidator` now accepts a `webhook-signature` header carrying several space-separated signatures (`v1,sigA v1,sigB`) and passes if any `v1,` entry matches ([#161](https://github.com/Coolhand-Labs/coolhand-ruby/pull/161)). Previously the whole remainder after `v1,` was compared as one value, so a legitimate webhook sent during secret rotation was rejected with a 401. Every candidate is compared in constant time, non-`v1` entries are ignored, a header that is not valid UTF-8 is rejected rather than raising, and the timestamp and replay-id checks still run only after a match. Single-signature headers behave as before. See [OpenAI Batch Webhook Handler](docs/openai.md#signature-header-and-secret-rotation).
+
+### Security
+- Warnings returned in a Coolhand log response are now sanitized before they are printed ([#162](https://github.com/Coolhand-Labs/coolhand-ruby/pull/162)): entries are coerced with `to_s`, invalid UTF-8 is scrubbed, control characters and line separators become a space, invisible Unicode format characters are removed, entries over 500 characters are truncated, and at most 5 are printed per response. Well-formed warnings print as before.
+
+### Documentation
+- `docs/declared_workloads.md` and the README now state that `Coolhand.with_context`, `with_capture` and `without_capture` are fiber-local, so work started in a new Fiber or Async task inside the block is not covered, and show opening the block inside the Fiber instead ([#160](https://github.com/Coolhand-Labs/coolhand-ruby/pull/160)).
+
 ## [0.8.0] - 2026-10-09
 
 ### Added

data/README.md

@@ -132,6 +132,29 @@ links.unlink_feedback('optimizationHashid', link[:id])
 
 For batching, error semantics, and details, see [Linking Feedback →](docs/feedback-links.md).
 
+## Declaring Workloads and Templates
+
+Tell Coolhand which workload and template an LLM call belongs to, instead of waiting for it to be matched. Calls captured inside the block carry the declared identity:
+
+```ruby
+Coolhand.with_context(reporter: 'my-app', workload: { key: 'Parser#call' }, template: { key: 'Parser#call/summarize' }) do
+  client.chat(...) # captured as usual
+end
+
+Coolhand.workload_service.upsert(key: 'Parser#call', name: 'Parser') # private key; create or rename
+```
+
+Or declare it once on the class and let every capture inside it pick it up, subclasses included:
+
+```ruby
+class ApplicationService
+  include Coolhand::Declarable
+  coolhand_declare_all # each public method declares "ClassName#method"
+end
+```
+
+For nesting rules, class-level declarations, Rails jobs and controllers, upserts, and public-key limits, see [Declared Workloads →](docs/declared_workloads.md).
+
 ## Rails Integration
 
 ### Configuration
@@ -212,6 +235,7 @@ end
 | `exclude_api_patterns` | Array | `["/batchPredictionJobs/"]` | Deny-list checked after `intercept_addresses`; matching paths are skipped. Unlike `intercept_addresses`, `exclude_api_patterns = []` genuinely disables exclusion. See [Configuration](docs/configuration.md) |
 | `max_captured_body_bytes` | Integer | `1_000_000` | Maximum size of a captured JSON request body — oversized bodies are replaced with a placeholder. Non-JSON bodies (e.g. file/audio uploads) are always skipped regardless of size — see [Advanced Configuration](docs/configuration.md) |
 | `async_logging` | Boolean | `true` | Send logs to Coolhand from a background thread so a slow Coolhand API never delays your LLM calls. Set to `false` to send inline — see [Advanced Configuration](docs/configuration.md#asynchronous-logging) |
+| `auto_declare` | Array | `[]` | Rails only: `:active_job` and/or `:controller` to declare a workload and template for LLM calls made from jobs and controller actions — see [Declared Workloads](docs/declared_workloads.md#rails-auto-declare) |
 
 ## Usage Examples
 
@@ -273,7 +297,7 @@ Coolhand.without_capture do
 end
 ```
 
-Both methods are thread-safe. Blocks nest correctly — the innermost block takes precedence, and the outer setting is restored when the block exits.
+Both methods are thread-safe. Blocks nest correctly — the innermost block takes precedence, and the outer setting is restored when the block exits. The override is fiber-local, so it does not follow into new Threads, Fibers or Async tasks started inside the block; see [Threads and background logging](docs/declared_workloads.md#threads-and-background-logging).
 
 ## Logging Inbound Webhooks
 
@@ -464,7 +488,7 @@ The monitor handles errors gracefully:
 - Failed API logging attempts are logged to console but don't interrupt your application
 - Invalid API keys will be reported but won't crash your app
 - Network issues are handled with appropriate error messages
-- The read methods (`search_templates`, `get_template`, `search_workloads`, `search_logs`, `get_log`) and the feedback-link methods are the exception — they raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses); see [Reading Templates →](docs/template-search.md), [Reading Workloads →](docs/workload-search.md), [Reading Logs →](docs/log-search.md) and [Linking Feedback →](docs/feedback-links.md)
+- The read methods (`search_templates`, `get_template`, `search_workloads`, `search_logs`, `get_log`), the feedback-link methods and the `upsert` methods are the exception — they raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses); see [Reading Templates →](docs/template-search.md), [Reading Workloads →](docs/workload-search.md), [Reading Logs →](docs/log-search.md), [Linking Feedback →](docs/feedback-links.md) and [Declared Workloads →](docs/declared_workloads.md)
 
 ## Documentation
 
@@ -474,6 +498,7 @@ The monitor handles errors gracefully:
 - **[Reading Workloads](docs/workload-search.md)** — List workloads with optional cost and performance metrics over a rolling or explicit time window
 - **[Reading Logs](docs/log-search.md)** — Search logs with per-log cost, filter and sort by cost, and fetch one log with its cost breakdown
 - **[Linking Feedback](docs/feedback-links.md)** — Link feedback to an optimization as evidence, singly or in bulk, using the private API key
+- **[Declared Workloads](docs/declared_workloads.md)** — Declare the workload and template of captured LLM calls with `Coolhand.with_context`, and create or rename them with `upsert`
 - **[Anthropic Integration](docs/anthropic.md)** — Official and community Anthropic Ruby gems, streaming, dual gem handling, and troubleshooting
 - **[ElevenLabs Integration](docs/elevenlabs.md)** — Webhook capture, feedback submission, and Rails integration
 - **[OpenAI Batch Webhook Handler](docs/openai.md)** — Handle OpenAI batch job completion events via webhook interception

data/Rakefile

@@ -9,4 +9,11 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+namespace :examples do
+  desc "Run every live script in examples/ against real provider keys (loads keys via zsh -ic)"
+  task :live do
+    sh RbConfig.ruby, File.expand_path("bin/live-examples", __dir__)
+  end
+end
+
 task default: %i[spec rubocop]

data/docs/declared_workloads.md

@@ -0,0 +1,156 @@
+# Declaring workloads and templates
+
+By default Coolhand works out which workload and template an LLM call belongs to by matching the log against known templates. If your code already knows (a service object, a prompt library, an adapter), declare it instead. A declared log skips matching entirely and is filed under the workload and template you named.
+
+There are two parts:
+
+- `Coolhand.with_context` stamps the LLM calls the gem captures automatically.
+- `Coolhand.workload_service.upsert` and `Coolhand.template_service.upsert` create or update workloads and templates explicitly. They need your **private** API key.
+
+## Declaring on captured calls
+
+```ruby
+Coolhand.with_context(
+  reporter: "squishling",
+  workload: { key: "Parser#call", name: "Parser#call", description: "Parses incoming tickets" },
+  template: { key: "Parser#call/squish:L2", name: "Parser#call · squish L2" }
+) do
+  client.chat(...) # captured as usual, and sent with the declared identity
+end
+```
+
+| Field | Accepts | Notes |
+|---|---|---|
+| `reporter` | String | Who is making the declaration, e.g. the library or app. Used when a record is first created. |
+| `workload` | Hash: `id`, `key`, `name`, `description` | Needs an `id` or a `key`. Other keys are ignored. |
+| `template` | Hash: `id`, `key`, `name` | Needs an `id` or a `key`. Other keys are ignored. |
+
+- `id` refers to an existing record. `key` is a stable string of your choosing; Coolhand finds or creates the record with that key. On a template, `id` wins over `key`.
+- `name`, `description` and `reporter` are used only when a record is **first created**. Declaring never renames or re-attributes an existing record; use `upsert` for that. A display name that is already taken gets a numeric suffix, and names such as "Unmatched" are reserved.
+- A declaration with only a `workload` gets a default template keyed `<workload key>/default`. A template given by `key` needs a workload alongside it, either in the same block or an enclosing one.
+- Keys are at most 255 characters, printable, and cannot start or end with whitespace or `/` or contain `//`. `#`, `:` and `·` are fine. Descriptions are cut to 1000 characters.
+- Keys must be stable, so never put a request id or timestamp in one: each distinct key creates a record.
+- A `workload` or `template` that is not a Hash, has neither `id` nor `key`, has an invalid key, or a template `key` with no workload raises `ArgumentError` before your block runs. The server would answer these with a `422` and **not save the log**.
+- An unknown `id` (or one from another client) gets the same `422` and the log is not saved, so prefer `key`.
+
+### Nesting
+
+Blocks nest. Each field (`reporter`, `workload`, `template`) is taken from the innermost block that sets it, and fields an inner block leaves out are inherited (with the one exception below):
+
+```ruby
+Coolhand.with_context(reporter: "my-app", workload: { key: "Parser#call" }) do
+  Coolhand.with_context(template: { key: "Parser#call/summarize" }) do
+    # reporter: "my-app", workload: Parser#call, template: Parser#call/summarize
+  end
+end
+```
+
+A template belongs to a workload, so an inner block that declares a `workload` without a `template` does not inherit the outer block's template. Declare both together when you change workload.
+
+A `workload` or `template` Hash is replaced as a whole, not merged key by key. An inner `workload: { key: "b" }` inside an outer `workload: { id: "a" }` declares only `b`, rather than a mix of `id` and `key`.
+
+### Threads and background logging
+
+The context is thread-local, like `Coolhand.with_capture`. It is also fiber-local, so it does not carry into threads, fibers, `Enumerator#next` blocks or async tasks you start inside the block; calls made there are captured without a declaration. The identity is read on the thread that made the LLM call, before the log is queued, so it survives `async_logging` (the default).
+
+This matters for Fiber-scheduler concurrency such as [Async](https://github.com/socketry/async). Nothing raises: the call is logged, just without a workload or template.
+
+```ruby
+Coolhand.with_context(workload: { key: "Parser#call" }) do
+  Async do
+    client.chat(...) # runs in a new Fiber: captured with no declared workload
+  end
+end
+```
+
+`Coolhand.with_capture` and `Coolhand.without_capture` work the same way, so a `without_capture` block does not suppress calls made from a Fiber started inside it, and with `config.capture = false` a `with_capture` block does not enable them. To cover work that runs in another Fiber, open the block inside that Fiber:
+
+```ruby
+Async do
+  Coolhand.with_context(workload: { key: "Parser#call" }) do
+    client.chat(...) # captured with the declared workload
+  end
+end
+```
+
+### Public keys
+
+Declarations made with a public key are capped per client at 200 workloads and 1,000 templates. Past the cap, Coolhand ignores the declaration, ingests the log normally, and returns a warning, which the gem prints unless `config.silent` is on. Server-supplied warnings are sanitized before printing (control and invisible characters removed, each entry cut at 500 characters, at most 5 printed per response). Declarations from a private key are not capped.
+
+Older Coolhand servers ignore `declared`, so it is safe to use against them.
+
+## Declaring on a class
+
+Wrapping every call site in `with_context` does not suit passive capture. Include `Coolhand::Declarable` and declare the identity once, on the class. Wrapped methods run inside `with_context`, so everything above (nesting, precedence, async) applies unchanged.
+
+```ruby
+class ApplicationService
+  include Coolhand::Declarable
+
+  coolhand_workload reporter: "my-app"
+  coolhand_declare_all
+end
+
+class Parser < ApplicationService
+  def call(ticket) = client.chat(...) # workload "Parser#call", template "Parser#call"
+end
+
+class Summariser < ApplicationService
+  coolhand_workload key: "Summariser" # one workload for every method; templates stay per method
+
+  def call(ticket) = client.chat(...) # workload "Summariser", template "Summariser#call"
+end
+```
+
+- `coolhand_declare :call, :other` wraps just those methods, whether they are defined before or after the line. `template:` takes a key or a `{ key:, name: }` Hash instead of the default `"ClassName#method"`: `coolhand_declare :call, template: "Parser#call/summarise"`.
+- `coolhand_declare_all` wraps every public instance method defined after it, in the class and its subclasses, so put it at the top of the class body. Private and protected methods are left alone, however they are made private (`private def`, `private :name`, or a `private` section), as are attribute readers and writers and object-protocol methods such as `to_s`, `==` and `method_missing`. A method you name in `coolhand_declare` is wrapped regardless.
+- The key uses the **runtime** class, so a method inherited from `ApplicationService` declares as `Parser#call` when called on a `Parser`. Anonymous classes are not declared.
+- `coolhand_workload(key:, name:, description:, reporter:)` sets class-level defaults and is inherited by subclasses, field by field, with the nearest class winning. Without a `key`, each method gets its own workload, `ClassName#method`. `name` and `description` need a `key`, since one name shared by per-method workloads would collide.
+- Services that call each other nest: the innermost wrapped method wins, and it brings its own template (see [Nesting](#nesting)).
+- It only works where the LLM call runs on the same thread and fiber as the wrapped method (see [Threads and background logging](#threads-and-background-logging)).
+
+## Rails auto-declare
+
+For Rails apps, Coolhand can declare jobs and controller actions without touching their classes. It is off by default, because every distinct job and action becomes a workload.
+
+```ruby
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_API_KEY")
+  config.auto_declare = [:active_job, :controller]
+end
+```
+
+| Target | Wraps | Declares |
+|---|---|---|
+| `:active_job` | `around_perform` on `ActiveJob::Base` | `SummariseJob#perform`, reporter `rails` |
+| `:controller` | `around_action` on `ActionController::Base` and `::API` | `UsersController#show`, reporter `rails` |
+
+Coolhand must be loaded after Rails (the default with `Bundler.require` in a Rails app), otherwise the hooks are never registered. They are installed after your initializers have run, so `Coolhand.configure` can come before or after anything else. Anything declared inside the job or action (a `Declarable` service, a `with_context` block) takes precedence over the job or action declaration. With a public API key the per-client declaration cap applies (see [Public keys](#public-keys)), so enable only the targets you want as workloads.
+
+## Creating and renaming explicitly
+
+```ruby
+Coolhand.configure { |config| config.api_key = ENV.fetch("COOLHAND_PRIVATE_API_KEY") }
+
+workload = Coolhand.workload_service.upsert(
+  key: "Parser#call", name: "Parser", description: "Parses incoming tickets", reporter: "my-app"
+)
+
+Coolhand.template_service.upsert(
+  key: "Parser#call/summarize",
+  workload: { key: "Parser#call" }, # or { id: workload[:id] }
+  name: "Parser · summarize",
+  reporter: "my-app"
+)
+```
+
+- Both are `PUT .../by_key/<key>`: they create the record if the key is new and update it otherwise. The server answers `201` on create and `200` on update; both return the record as a Hash.
+- The key never changes. Calling `upsert` with the same key and a new `name` renames the record, and an update changes only the fields you send.
+- A template needs a `workload` (`{ id: }` or `{ key: }`, sent to the server as `workload_id` / `workload_key`) when it is new. For an existing template, naming a different workload is a `422`.
+- A key may contain `/`, `#`, `:` and other characters; the gem escapes it for the URL.
+
+## Errors
+
+`upsert` raises, unlike the logging writes. A non-2xx response raises `Coolhand::HttpError` whose `status` is the HTTP code (`401` for a missing or public key, `422` for an invalid key, a taken name, a missing or unknown workload, or a key held by a deprecated template, `504` if the server timed out). A blank key, or one made of `.` / `..` path segments, and transport failures raise `Coolhand::Error`; a `workload` that is not a Hash raises `ArgumentError`.
+
+`config.debug_mode` does not suppress `upsert`: it changes server state, so it is always sent.

data/docs/openai.md

@@ -59,6 +59,10 @@ end
 # ...existing code...
 ```
 
+## Signature header and secret rotation
+
+The `webhook-signature` header may carry several space-separated signatures (`v1,sigA v1,sigB`), as senders produce while a webhook secret is being rotated. `Coolhand::OpenAi::WebhookValidator` accepts the request if any `v1,` entry matches your secret, comparing each in constant time and ignoring entries with any other version prefix. The timestamp and replay checks below still run, and only after a signature matches.
+
 ## Replay protection
 
 `Coolhand::OpenAi::WebhookValidator` rejects requests whose `webhook-timestamp` is more than **300 seconds** away from the current time, and rejects a `webhook-id` it has already seen within that window — this prevents a captured request (from a log aggregator, APM trace, or proxy log) from being replayed to re-trigger `Coolhand::OpenAi::BatchResultProcessor`.

data/lib/coolhand/api_service.rb

@@ -6,12 +6,14 @@ require "json"
 require_relative "collector"
 require_relative "errors"
 require_relative "read_requests"
+require_relative "response_warnings"
 
 module Coolhand
   class ApiService
     # The GET half of this class. See Coolhand::ReadRequests for why reads raise where writes
     # log and return nil.
     include ReadRequests
+    include ResponseWarnings
 
     # Caps how much of a failed response body is interpolated into a log line or an exception
     # message. Without it an oversized body from a proxy or gateway becomes the message.
@@ -36,7 +38,9 @@ module Coolhand
         log JSON.pretty_generate(sanitize_payload_for_json(payload))
         nil
       else
-        send_request(payload, "✅ Successfully sent request metadata")
+        result = send_request(payload, "✅ Successfully sent request metadata")
+        log_response_warnings(result)
+        result
       end
     end
 

data/lib/coolhand/base_interceptor.rb

@@ -149,7 +149,8 @@ module Coolhand
     end
 
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
-      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil)
+      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil,
+      declared: nil)
       raw_request = {
         id: request_id,
         timestamp: start_time.iso8601,
@@ -168,6 +169,7 @@ module Coolhand
       raw_request[:model] = model if Coolhand.required_field?(model)
 
       request_data = { raw_request: raw_request }
+      request_data[:declared] = declared if declared && !declared.empty?
 
       LogQueue.submit do
         Coolhand::ApiService.new.send_llm_request_log(request_data)

data/lib/coolhand/configuration.rb

@@ -30,7 +30,7 @@ module Coolhand
 
     attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled,
       :max_captured_body_bytes, :webhook_replay_tolerance_seconds, :webhook_id_store, :async_logging
-    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url
+    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url, :auto_declare
 
     def initialize
       # Set defaults
@@ -45,6 +45,7 @@ module Coolhand
       @exclude_api_patterns = DEFAULT_EXCLUDE_API_PATTERNS.dup
       @enabled = true
       @async_logging = true
+      @auto_declare = []
       @max_captured_body_bytes = DEFAULT_MAX_CAPTURED_BODY_BYTES
       @webhook_replay_tolerance_seconds = 300
       @webhook_id_store = Coolhand::OpenAi::WebhookIdStore.new
@@ -74,6 +75,18 @@ module Coolhand
       @intercept_path_patterns = value.is_a?(Array) ? value : [value]
     end
 
+    # Rails entry points to declare a workload/template for automatically: any of
+    # RailsAutoDeclare::TARGETS (:active_job, :controller). Off by default. See docs/declared_workloads.md.
+    def auto_declare=(value)
+      targets = Array(value).map { |target| target.to_s.to_sym }
+      unknown = targets - RailsAutoDeclare::TARGETS
+      unless unknown.empty?
+        raise Error, "auto_declare supports #{RailsAutoDeclare::TARGETS.inspect}, got #{unknown.inspect}"
+      end
+
+      @auto_declare = targets.uniq
+    end
+
     def base_url=(value)
       stripped = value&.sub(%r{/+\z}, "")
       raise Error, BASE_URL_ERROR_MSG unless stripped.nil? || valid_base_url?(stripped)

data/lib/coolhand/declarable.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Declares the workload/template of the LLM calls a class makes, once, on the class, so passive
+  # capture picks them up without a `Coolhand.with_context` block at every call site. Wrapped methods
+  # run inside `with_context`, so nesting and precedence are exactly those documented in
+  # docs/declared_workloads.md. Settings are inherited by subclasses.
+  #
+  #   class ApplicationService
+  #     include Coolhand::Declarable
+  #     coolhand_workload reporter: "my-app"
+  #     coolhand_declare_all
+  #   end
+  #
+  #   class Parser < ApplicationService
+  #     def call = client.chat(...) # workload "Parser#call", template "Parser#call"
+  #   end
+  module Declarable
+    def self.included(base)
+      raise ArgumentError, "Coolhand::Declarable can only be included in a class" unless base.is_a?(Class)
+
+      base.extend(ClassMethods)
+    end
+
+    # Never an LLM call site, and wrapping them would tax every call or declare a junk workload.
+    SKIPPED_METHODS = %i[method_missing respond_to? respond_to_missing? == === eql? equal? hash to_s inspect
+                         to_str to_ary to_proc coerce <=>].freeze
+    ATTRIBUTE_MACROS = %w[attr attr_reader attr_writer attr_accessor].freeze
+    private_constant :SKIPPED_METHODS, :ATTRIBUTE_MACROS
+
+    module ClassMethods
+      # Class-level defaults, inherited field by field (the nearest class that sets a field wins). With
+      # no `key`, each wrapped method declares its own workload, "ClassName#method"; a `key` makes every
+      # method share one workload. The class name is the runtime class, so an inherited method declares
+      # under the subclass.
+      def coolhand_workload(key: nil, name: nil, description: nil, reporter: nil)
+        workload = DeclaredContext.normalize_part(:workload, { key: key, name: name, description: description }.compact,
+          DeclaredContext::WORKLOAD_FIELDS)
+        @coolhand_settings = { workload: workload, reporter: DeclaredContext.normalize_reporter(reporter) }.compact
+      end
+
+      # Wraps the named instance methods (now, or when they are defined later). `template:` is a key or a
+      # `{ key:, name: }` Hash; by default the template key is "ClassName#method".
+      def coolhand_declare(*names, template: nil)
+        # Checked here, at class definition, so a bad value never surfaces inside the host's method.
+        template = DeclaredContext.normalize_part(:template, template.is_a?(String) ? { key: template } : template,
+          DeclaredContext::TEMPLATE_FIELDS)
+        names.flatten.each do |name|
+          name = name.to_sym
+          (@coolhand_declared ||= {})[name] = { template: template }
+          coolhand_wrap(name) if method_defined?(name) || private_method_defined?(name)
+        end
+      end
+
+      # Wraps every public instance method defined in this class and its subclasses after this call, so
+      # put it at the top of the class body. Private and protected methods, attribute readers/writers
+      # and object-protocol methods (see SKIPPED_METHODS) are left alone; `coolhand_declare` wraps one of
+      # those if you name it.
+      def coolhand_declare_all
+        @coolhand_declare_all = true
+      end
+
+      # @api private
+      def coolhand_identity(method_name)
+        key = "#{name}##{method_name}"
+        template = coolhand_template_for(method_name)
+        {
+          reporter: coolhand_setting(:reporter),
+          workload: { key: key }.merge(coolhand_setting(:workload) || {}),
+          template: template || { key: key }
+        }
+      end
+
+      # @api private
+      def coolhand_declare_call?(method_name)
+        return false if name.nil? || !Coolhand.configuration.enabled
+        return false unless DeclaredContext.valid_key?("#{name}##{method_name}")
+
+        public_method_defined?(method_name) || !coolhand_declaration(method_name).nil?
+      end
+
+      # @api private
+      def coolhand_own_state
+        [@coolhand_settings, @coolhand_declared, @coolhand_declare_all]
+      end
+
+      private
+
+      def method_added(method_name)
+        super
+        coolhand_wrap(method_name) if !@coolhand_wrapping && coolhand_wrap?(method_name)
+      end
+
+      def coolhand_wrap?(method_name)
+        return true if coolhand_declaration(method_name)
+
+        public_method_defined?(method_name) && !SKIPPED_METHODS.include?(method_name) &&
+          coolhand_declare_all? && !attribute_definition?
+      end
+
+      # True while `attr_reader`/`attr_writer`/`attr_accessor` is what is defining the method. Read from
+      # the stack rather than by overriding those macros, which would lose the class body's
+      # `private`/`protected` default visibility. A window of frames, not one fixed depth, so a
+      # `method_added` override that calls `super` does not hide the macro.
+      def attribute_definition?
+        caller_locations(1, 8)&.any? { |frame| ATTRIBUTE_MACROS.include?(frame.base_label) } || false
+      end
+
+      def coolhand_declare_all?
+        coolhand_each_class { |klass| return true if klass.coolhand_own_state[2] }
+        false
+      end
+
+      # Redefines the method in the same class, rather than prepending a wrapper, so a later
+      # `private :name` (or `private def name`) applies to the wrapper like it would to the original.
+      def coolhand_wrap(method_name)
+        original = instance_method(method_name)
+        wrappers = (@coolhand_wrappers ||= {})
+        return if wrappers[method_name] == original
+
+        visibility = coolhand_visibility(method_name)
+        @coolhand_wrapping = true
+        define_method(method_name) do |*args, **kwargs, &block|
+          klass = self.class
+          next original.bind_call(self, *args, **kwargs, &block) unless klass.coolhand_declare_call?(method_name)
+
+          Coolhand.with_context(**klass.coolhand_identity(method_name)) do
+            original.bind_call(self, *args, **kwargs, &block)
+          end
+        end
+        send(visibility, method_name)
+        wrappers[method_name] = instance_method(method_name)
+      ensure
+        @coolhand_wrapping = false
+      end
+
+      # Includes inherited methods: wrapping one a parent made private must not make it public here.
+      def coolhand_visibility(method_name)
+        return :private if private_method_defined?(method_name)
+        return :protected if protected_method_defined?(method_name)
+
+        :public
+      end
+
+      # Yields this class and its superclasses that include Declarable, nearest first. A loop rather
+      # than a collected Array, since the lookups below run on every wrapped call.
+      def coolhand_each_class
+        klass = self
+        while klass.respond_to?(:coolhand_own_state)
+          yield klass
+          klass = klass.superclass
+        end
+      end
+
+      def coolhand_declaration(method_name)
+        coolhand_nearest(1, method_name)
+      end
+
+      def coolhand_template_for(method_name)
+        coolhand_declaration(method_name)&.fetch(:template)
+      end
+
+      def coolhand_setting(field)
+        coolhand_nearest(0, field)
+      end
+
+      # The value for `key` in the nearest class whose own state (slot `slot` of `coolhand_own_state`)
+      # sets it, or nil.
+      def coolhand_nearest(slot, key)
+        coolhand_each_class do |klass|
+          state = klass.coolhand_own_state[slot]
+          return state[key] if state&.key?(key)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/coolhand/declared_context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Ambient workload/template identity for captured calls, set with {Coolhand.with_context}. The
+  # interceptor snapshots {current} on the calling thread before a log is queued, because the
+  # background log worker does not inherit thread-locals. See docs/declared_workloads.md.
+  module DeclaredContext
+    THREAD_KEY = :coolhand_declared_context
+
+    # The fields the server accepts under `declared.workload` / `declared.template`; anything else
+    # is dropped here rather than sent.
+    WORKLOAD_FIELDS = %i[id key name description].freeze
+    TEMPLATE_FIELDS = %i[id key name].freeze
+
+    module_function
+
+    # A frozen Hash, or nil when no context is active.
+    def current
+      Thread.current[THREAD_KEY]
+    end
+
+    def clear!
+      Thread.current[THREAD_KEY] = nil
+    end
+
+    # Each field is replaced wholesale by the innermost block that sets it. Hashes are not merged
+    # key by key: `{ id: x }` merged with `{ key: y }` would declare both, and the server prefers `id`.
+    # A template belongs to a workload, so a block that declares a workload without a template does
+    # not inherit the outer one; it would pair the new workload with a template from another.
+    def with(reporter: nil, workload: nil, template: nil)
+      previous = current
+      declared = {
+        reporter: normalize_reporter(reporter),
+        workload: normalize_part(:workload, workload, WORKLOAD_FIELDS),
+        template: normalize_part(:template, template, TEMPLATE_FIELDS)
+      }.compact
+      inherited = previous || {}
+      inherited = inherited.except(:template) if declared.key?(:workload) && !declared.key?(:template)
+      merged = inherited.merge(declared)
+      ensure_template_has_workload!(merged)
+      Thread.current[THREAD_KEY] = merged.empty? ? nil : merged.freeze
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = previous
+    end
+
+    def normalize_reporter(reporter)
+      return nil if reporter.nil?
+
+      reporter.to_s
+    end
+
+    # Mirrors the server's key rules: at most 255 characters, no control or invisible characters, no
+    # leading or trailing whitespace, and no leading, trailing or doubled "/". The server answers a
+    # bad key with a 422 that rejects the whole log, so it is checked here, before the call is made.
+    MAX_KEY_LENGTH = 255
+    KEY_FORMAT = %r{
+      \A(?!/)(?!.*//)
+      [^\p{Cntrl}\p{Cf}[:space:]]
+      (?:[^\p{Cntrl}\p{Cf}]*[^\p{Cntrl}\p{Cf}[:space:]])?
+      (?<!/)\z
+    }x
+
+    def valid_key?(key)
+      key.is_a?(String) && key.length <= MAX_KEY_LENGTH && KEY_FORMAT.match?(key)
+    rescue ArgumentError, EncodingError
+      false # a string with a broken or incompatible encoding is not a valid key
+    end
+
+    # A template given by key, with no workload to create it in, is a 422 that drops the log. A
+    # template `id` refers to an existing record and needs no workload.
+    def ensure_template_has_workload!(declared)
+      template = declared[:template]
+      return if template.nil? || template.key?(:id) || declared.key?(:workload)
+
+      raise ArgumentError, "template with a :key needs a workload; declare one in this or an enclosing block"
+    end
+
+    # Validated up front: the server answers a non-object `workload`/`template` with a 422 for the
+    # whole log, which would drop the call from Coolhand rather than just its identity.
+    def normalize_part(name, value, fields)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+      part = value.each_with_object({}) do |(k, v), acc|
+        field = k.respond_to?(:to_sym) ? k.to_sym : nil
+        next unless fields.include?(field) && !v.nil?
+        # A blank id refers to nothing and would 422 the log, so it counts as not given.
+        next if field == :id && v.to_s.strip.empty?
+
+        acc[field] = v.to_s.dup.freeze
+      end
+      return nil if part.empty?
+
+      if part.key?(:key) && !valid_key?(part[:key])
+        raise ArgumentError, "#{name} key must be at most #{MAX_KEY_LENGTH} printable characters with no " \
+                             "surrounding whitespace and no leading, trailing or doubled \"/\""
+      end
+      unless part.key?(:id) || part.key?(:key)
+        raise ArgumentError, "#{name} needs an :id or a :key, got #{value.keys.inspect}"
+      end
+
+      part.freeze
+    end
+  end
+end

data/lib/coolhand/log_service.rb

@@ -47,13 +47,7 @@ module Coolhand
         per: per
       }.compact
 
-      logs, response = get_json_with_headers(list_url(query), ERROR_NOUN)
-      raise Error, "#{ERROR_NOUN} response was not a JSON array" unless logs.is_a?(Array)
-
-      LogSearchResult.new(
-        logs: logs,
-        pagination: Pagination.from_headers(response, items: logs, page: page, per: per)
-      ).freeze
+      fetch_list(query, LogSearchResult, :logs, page: page, per: per)
     end
 
     # The full log, with `cost` and `cost_breakdown`. Both are nil when the log has no tokens or its

data/lib/coolhand/logger_service.rb

@@ -15,24 +15,8 @@ module Coolhand
     # Helper method for forwarding webhook data to Coolhand
     def forward_webhook(webhook_body:, source:, event_type: nil, headers: {}, **options)
       # Validate required parameters
-      unless Coolhand.required_field?(webhook_body)
-        error_msg = "webhook_body is required and cannot be nil or empty"
-        if Coolhand.configuration.silent
-          puts "COOLHAND WARNING: #{error_msg}"
-          return false
-        else
-          raise ArgumentError, error_msg
-        end
-      end
-
-      unless Coolhand.required_field?(source)
-        error_msg = "source is required and cannot be nil or empty"
-        if Coolhand.configuration.silent
-          puts "COOLHAND WARNING: #{error_msg}"
-          return false
-        else
-          raise ArgumentError, error_msg
-        end
+      { webhook_body: webhook_body, source: source }.each do |name, value|
+        return reject_webhook("#{name} is required and cannot be nil or empty") unless Coolhand.required_field?(value)
       end
 
       # Auto-generate required fields unless provided
@@ -55,6 +39,14 @@ module Coolhand
 
     private
 
+    # Silent mode warns and drops the webhook; otherwise the caller gets the error.
+    def reject_webhook(error_msg)
+      raise ArgumentError, error_msg unless Coolhand.configuration.silent
+
+      puts "COOLHAND WARNING: #{error_msg}"
+      false
+    end
+
     def build_webhook_url(source, event_type)
       base = "webhook://#{source}"
       event_type ? "#{base}/#{event_type}" : base

data/lib/coolhand/net_http_interceptor.rb

@@ -46,13 +46,12 @@ module Coolhand
           Net::HTTPResponse.prepend(ResponseInterceptor)
 
           @patched = true
-          Coolhand.log "🔗 Net::HTTP interceptor patched"
         rescue StandardError
           # Roll back this call's hold — it never actually took effect, so it must not count
           # toward the refcount or a legitimate later unpatch! would underflow against it. This
           # branch only runs when @patched was false on entry (see `next if @patched` above), so
           # forcing it back to false here is correct regardless of which line above raised —
-          # including a failure in the log call itself, after prepend already succeeded.
+          # including a failure in the second prepend, after the first already succeeded.
           @patch_count -= 1
           @patched = false
           raise
@@ -139,7 +138,9 @@ module Coolhand
         end_time = Time.now
         duration_ms = ((end_time - start_time) * 1000).round(2)
 
+        # Read here on the calling thread: the log worker thread has no access to our thread-locals.
         BaseInterceptor.send_complete_request_log(
+          declared: DeclaredContext.current,
           request_id: request_id,
           method: req.method,
           url: url,

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/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

@@ -4,6 +4,7 @@ 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
@@ -17,6 +18,19 @@ module Coolhand
       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)
 

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.9.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"
@@ -21,6 +24,8 @@ require_relative "coolhand/optimization_feedback_link_service"
 require_relative "coolhand/workload_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 +40,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 +80,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
@@ -149,5 +160,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.9.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-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -47,6 +47,7 @@ files:
 - SECURITY.md
 - docs/anthropic.md
 - docs/configuration.md
+- docs/declared_workloads.md
 - docs/elevenlabs.md
 - docs/feedback-links.md
 - docs/feedback.md
@@ -60,6 +61,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 +77,11 @@ files:
 - lib/coolhand/open_ai/webhook_validator.rb
 - lib/coolhand/optimization_feedback_link_service.rb
 - lib/coolhand/pagination.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