coolhand 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25393afdf95625b624ca2910cb3017685705529e9628a5d15cb3bdffdf122d52
-  data.tar.gz: 3e478c3b8494d5fef5bc87896fbf69cb9f93d088029b9a9745563c9a789b4473
+  metadata.gz: a3c1e767ea245f56520ee634e48cd2f12c6dc06be79b3998537fea9e9b8ea9ff
+  data.tar.gz: aad0485d474aa1e3f796f2af30083304a1ed704ede8428ddc4b0c9a4ff32678e
 SHA512:
-  metadata.gz: ad635f9377f6cb81967fc24b0c2aa9f9938c41e308c6b98511ee0139b9938e01ea766baf72a085700866c69ac50207da11e29f04d30a94ad3b487d3e22243d9e
-  data.tar.gz: d6ef0baf4e37d29b36a0d7a2d6a41822f551a0a753a2dc963c0da9eed60b90bf29b5f0015caa8a628c6f340ec9cb2b3ef2c83ecb9b59fbcec909d70f396603df
+  metadata.gz: 2b497e1401c64e9eb6a6b1bbb061ecb359985a39f8dd95ce8018406d36e3c49ba061e5557299d4e6ee00498f8f8bf91ac9f3b91e56a32f5b08af599f5ef16768
+  data.tar.gz: 84d13bff930f045607270849ad02fd5c8548b15b39f2043636c868bcfe857e04fab4c0ae113fe4e5872ca299d197c83b04c2f0adce5bffe3723c4bacd5890b03

data/AGENTS.harness.md

@@ -0,0 +1,139 @@
+# RUBY agent — API client harness
+
+You are the **ruby agent**, working in the `coolhand-ruby` gem repo. You wrap one server
+endpoint, prove it against the live local server, open a PR, and **stop**.
+
+You are a dead end in the tree. You launch nobody.
+
+This file is self-contained. You do not share a context window with the agent that
+launched you.
+
+---
+
+## 0. Your inputs
+
+```
+node <workspaceRoot>/coolhand/harness/harness.mjs context --run <RUN_DIR>
+```
+
+| field | meaning |
+|---|---|
+| `baseUrl` | the live local server, already booted for you |
+| `branch` | the shared branch name — use it here too |
+| `specPath` | `coolhand/swagger/v2/coolhand_api.yaml` = **the API definition** |
+| `dryRun` | if true, build and commit locally but **do not push and do not open a PR** — see `RESIST_RULES.md` → Dry runs |
+
+Your channel is `ruby`. Your parent is `node`.
+
+**Node opened a GitHub issue for you before it launched you.** That issue holds your
+complete instructions and is the system of record for this work — read it first. Read your
+own number back at any time with:
+
+```
+node <workspaceRoot>/coolhand/harness/harness.mjs my-issue --run <RUN_DIR> --repo ruby
+```
+
+## 1. Read before writing any code
+
+1. **Your issue.** It is what you were asked to build.
+2. `<workspaceRoot>/coolhand/harness/RESIST_RULES.md` — the refuse list.
+3. The API definition at `specPath`. It is your only source of truth **for the endpoint's
+   contract** — paths, params, response fields, status codes.
+4. `coolhand-ruby/CLAUDE.md` — this repo's own rulebook. **It is authoritative.** Where it
+   disagrees with this harness file, CLAUDE.md wins — follow it and say so in your PR.
+
+**Your issue links node's PR as the reference implementation. Use it for structure, not
+for facts.** Node went first so you do not have to rediscover how a REST method fits into
+a monitoring SDK — copy its *shape*: which class the method hangs off, how errors surface,
+how pagination is exposed, what the method is called.
+
+**Do not take a field name, a param, or a status code from node's code.** Those come from
+the definition, every time. If node's wrapper and the definition disagree, that is not
+yours to reconcile — it means one of them is wrong. Escalate (R3) and STOP.
+
+Naming does not port. `searchFeedback` in node is `search_feedback` here. Match the
+concept, not the characters.
+
+## 2. Build the wrapper
+
+1. `git checkout -b <branch>`
+2. Add the method following the existing pattern in `lib/coolhand/` —
+   `api_service.rb` and `feedback_service.rb` are your references.
+3. Require/expose it the way existing surface is exposed in `lib/coolhand.rb`.
+4. Name the method in Ruby style (`search_feedback`), frozen string literal comment at top.
+
+**Do not restructure the gem to make this fit (R5).** If the endpoint cannot be expressed
+inside the current architecture, escalate and STOP.
+
+**Never add a provider SDK `require` (openai, anthropic, google-generativeai, etc.) to
+`lib/coolhand.rb`, and never add one to `coolhand-ruby.gemspec` as a hard dependency (R5).**
+Require it inside the file that actually uses it, executed only when that provider's
+functionality is accessed. Clients may not use every provider and must not be forced to
+install gems they do not need — apps consuming this as a path gem break on missing optional
+dependencies. See `coolhand-ruby/CLAUDE.md`.
+
+## 3. Prove it against the real server
+
+Not a mock. Make real calls to `baseUrl`.
+
+```
+bundle exec rake
+```
+
+That runs both RSpec and RuboCop — both must pass. **Never delete an assertion, mark a
+spec pending, or rescue-and-swallow to get green (R4).**
+
+**RSpec is the normal, correct test framework in this gem.** If you have seen the rule
+that RSpec is only for API-definition docs — that is the `coolhand` Rails repo, which
+migrated to Minitest and kept RSpec solely to generate the API docs. It does not apply
+here. Write RSpec.
+
+## 4. Escalate the moment something does not make sense
+
+Escalate to **node**, your parent — not to the server. If it is a question about the API
+definition, node passes it up and relays the answer back down. You never message the
+server directly; the tree only has parents and children.
+
+```
+node <workspaceRoot>/coolhand/harness/harness.mjs send --run <RUN_DIR> --channel ruby \
+  --from ruby --to node --kind escalation --text "R2: definition exposes POST /get_optimization"
+```
+
+Then wait, and stop working while you wait:
+
+```
+node <workspaceRoot>/coolhand/harness/harness.mjs wait --run <RUN_DIR> --channel ruby --for ruby --after <messageId>
+```
+
+Name the rule number (`R1`–`R5`). Do not guess. Do not stub. Do not work around it.
+
+## 5. Run your review skill
+
+**Mandatory, before you push.** Follow `<workspaceRoot>/coolhand/harness/RESIST_RULES.md`
+→ "Before you push: run your repo's review skill" (R8) — load
+`.claude/skills/loop-review/SKILL.md` off disk and run it for real against your diff. Do
+not approximate its steps manually; if you cannot spawn the reviewer subagent it calls
+for, escalate to node (R8) and STOP rather than substitute a self-review.
+
+## 6. Open your PR — then STOP
+
+**If `dryRun` is true, stop here.** Commit locally, report what you built, and push nothing.
+
+1. Push and open the PR in `coolhand-ruby`.
+2. Body must reference your issue with `Closes #N` so it auto-closes on merge, and must
+   say: **depends on the server PR — deploy that first.**
+3. Record it: `node <workspaceRoot>/coolhand/harness/harness.mjs pr --run <RUN_DIR> --repo ruby --url <url>`
+4. Post your review skill's Iteration Breakdown table (section 5) as a comment on this PR
+   — see `RESIST_RULES.md` → "After the loop exits."
+5. **Stop.** You launch no one. The tree ends with you on this branch.
+
+## 7. Done means
+
+- [ ] Method exists, matches the API definition exactly
+- [ ] `bundle exec rake` passes (RSpec + RuboCop)
+- [ ] At least one spec hit the real local server, not a mock
+- [ ] PR opened, recorded, references its issue, states its dependency on the server PR
+- [ ] Your review skill ran for real (not approximated) and its Iteration Breakdown table
+      is posted as a comment on your PR
+- [ ] Every field and status code came from the definition, not from node's code
+- [ ] You launched no child agents

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-12
+
+### Added
+- **`Coolhand::TemplateService`, reached via `Coolhand.template_service`** — reads LLM request templates back out of Coolhand (`GET /api/v2/llm_request_templates`, `GET /api/v2/llm_request_templates/{id}`). `search_templates` filters and pages, returning a `Coolhand::TemplateSearchResult` of `templates` and `pagination`; `get_template` adds the `user_prompt_pattern`/`system_prompt_pattern` regexes the list omits. Both require the **private** API key — the public key is write-only on this API. Needs a server carrying these endpoints; a self-hosted one that predates them answers `404`. See [docs/template-search.md](docs/template-search.md) (#105).
+- **`Coolhand::HttpError`** — raised by the read methods on a non-2xx response, carrying `#status` and `#body` so a caller can branch on `401` vs `404` vs `504` without matching message text. It subclasses `Coolhand::Error`, so `rescue Coolhand::Error` still catches everything this gem raises.
+- **OpenCode added to default intercept addresses** — `opencode.ai` (OpenCode Zen's OpenAI-compatible gateway) is now monitored out of the box with no configuration required. Since matching is now host-based (see Security below), this also covers requests to `api.opencode.ai` without needing a separate entry, so misrouted requests show up in logs instead of vanishing (#97).
+- **`examples/`** — runnable scripts (`openai_example.rb`, `anthropic_example.rb`, `elevenlabs_example.rb`) that make a real provider call through Coolhand, useful as a live smoke test. Excluded from the packaged gem. See [Examples](examples/README.md) (#109).
+
+### Changed
+- **`config.intercept_addresses = []` (or `nil`) now logs a warning instead of silently doing nothing.** `intercept_addresses` is a required allow-list — an empty list would mean "capture nothing" — so `[]` has always been ignored and the previous value kept, unlike the deny-list `exclude_api_patterns`, which genuinely supports `= []` to disable exclusion. That asymmetry meant a user modeling `intercept_addresses` on its sibling setting got no error and no signal that anything happened. Behavior is unchanged; it's just no longer silent. Documented next to both settings in `docs/configuration.md` and the README (#89).
+- **The read methods raise where the write methods return `nil`.** `send_llm_request_log`, `create_log` and `create_feedback` still log a failure and return `nil`; the new read methods raise `Coolhand::HttpError`, because a caller that asked for data has to be able to tell a `404` from a timeout from a genuinely empty result. Reads also allow 60 seconds where writes allow 5.
+- **`search_templates` is not a port of the `search_templates` MCP tool and does not agree with its numbers.** `log_count` here counts only directly-collected client logs, so evals, bakeoff comparisons and synthetic logs are excluded; templates whose workload has been archived are returned rather than hidden.
+- `Coolhand::Error` moved from `lib/coolhand.rb` into a new `lib/coolhand/errors.rb`, alongside `Coolhand::HttpError`, and is now required first. The constant, its superclass and its behaviour are unchanged.
+- The GET half of `Coolhand::ApiService` now lives in a `Coolhand::ReadRequests` mixin (`lib/coolhand/read_requests.rb`), keeping the class inside this repo's 200-line budget, with `format_error_body` and `apply_headers` extracted from the POST path and shared by both halves. The one write-path behaviour change: a failed response body over 2000 characters is now truncated in the log line instead of printed in full.
+
+### Security
+- **`NetHttpInterceptor`'s patched/unpatched state is no longer a plain boolean shared across threads.** `Coolhand.capture` snapshotted `NetHttpInterceptor.patched?` before yielding and used that snapshot at the end of a potentially long-running block (an in-flight HTTP request) to decide whether to unpatch. Two threads concurrently entering `Coolhand.capture` before the interceptor was already permanently patched could both observe `patched? == false`, and whichever thread's block finished first would call `unpatch!`, silently disabling interception for the other thread's still in-flight request. `patch!`/`unpatch!` are now a mutex-guarded reference count, so overlapping/nested callers compose correctly and the interceptor only actually unpatches once every outstanding caller has released it (#90). One behavior change: `patch!` is no longer idempotent on its own — every call now needs a matching `unpatch!` to release it, so an app that calls `Coolhand.configure` more than once (e.g. a reloader re-running an initializer) holds an extra, permanent reference each time rather than no-op'ing. This is harmless (interception simply stays on) but is a change from the prior behavior.
+- **Captured request bodies are now capped in size and skipped entirely for non-JSON content types.** `Coolhand::NetHttpInterceptor#capture_request_body` previously read the entirety of `req.body_stream` (or `req.body`/the `body` param) into memory with no limit and forwarded it in full as `request_body` — since `intercept?` matches configured hosts on any path, a large upload to an endpoint like `/v1/files`, `/v1/audio/transcriptions`, or `/v1/batches` was held in memory and shipped to Coolhand's API in its entirety. A binary/multipart upload (audio, a batch JSONL file, a fine-tune corpus) is now skipped before it's ever read into memory for capture, and any body over the new `config.max_captured_body_bytes` (default 1 MB) is replaced with a placeholder instead of the full content. The real request to the LLM provider is unaffected — only what gets captured/logged changes (#88).
+- **`Coolhand::OpenAi::WebhookValidator#should_enforce_strict_validation?` no longer fails open on unrecognized `Rails.env` names.** It previously blocklisted `"production"`/`"staging"` exactly, so any other spelling — `"prod"`, `"production-eu"`, a Heroku/Render `"review"` app env, or an unset `Rails.env` — fell into the permissive fallback path, where a missing/misconfigured webhook secret let an unsigned request pass as valid. It now uses a fail-safe allowlist of `"development"`/`"test"` — every other value, including `nil`, enforces strict validation (#84).
+- **The full captured request/webhook body is no longer printed to stdout by default.** `Coolhand::ApiService#log_request_info` (reached via `LoggerService#log_to_api`/`#forward_webhook`) previously dumped the entire captured payload — including raw webhook bodies like voice-call transcripts — to stdout whenever `silent` was `false` (the default). In a containerized deploy, stdout typically flows straight into a log aggregator with a different retention/access model than Coolhand itself. It now logs only an identifier and a byte count by default; the full payload is still printed when `debug_mode` is explicitly enabled (#87).
+- **A previously-valid OpenAI webhook request can no longer be replayed indefinitely.** `Coolhand::OpenAi::WebhookValidator#verify_signature` included `webhook-timestamp` and `webhook-id` in the signed payload, but never checked the timestamp for freshness or tracked the id for idempotency — a signature computed over a `webhook-timestamp` from the past (e.g. captured from a log aggregator, an APM trace, or a proxy log) still validated as `true`, and each replay re-triggered `Coolhand::OpenAi::BatchResultProcessor`, causing redundant OpenAI file downloads and duplicate request logs. It now rejects requests whose `webhook-timestamp` is more than `Coolhand.configuration.webhook_replay_tolerance_seconds` (default 300, matching the Standard Webhooks tolerance) away from the current time, and atomically claims `webhook-id` via a new `Coolhand.configuration.webhook_id_store` (default: an in-memory, per-process, TTL-bounded store — swappable for multi-process deployments), rejecting a request whose id was already claimed within the window. A missing `webhook-id` header (previously only the signature/timestamp headers were required) is now also treated as a missing-headers failure, rather than falling through as `nil` and letting two distinct requests both dedupe against the same `nil` key (#86).
+- **`intercept_addresses` and `exclude_api_patterns` no longer match against the raw URL string.** `Coolhand::NetHttpInterceptor#intercept?`/`#excluded_by_pattern?` previously did `url.include?(entry)` against the whole URL, so a configured entry like `"api.openai.com"` could be triggered by an attacker-controlled URL that merely *mentions* it — `https://evil.com/redirect?to=api.openai.com` (wrong destination) or `https://api.openai.com.attacker.net/...` (suffix confusion) both wrongly matched, while `https://API.OPENAI.COM/...` wrongly didn't (case-sensitive). Matching is now done against the parsed `uri.host`, exact or dot-boundary suffix, case-insensitively — so a request can only be captured because it's actually going to a configured host. `exclude_api_patterns` now matches only `uri.path`, so a pattern like `/batchPredictionJobs/` can no longer be tripped by an unrelated request that merely has it in a query string.
+- **Bare, hostless entries (`:generateContent`, `:streamGenerateContent`) have moved out of `intercept_addresses` into a new `intercept_path_patterns` setting.** These colon-suffixed path tokens (Google's API Discovery convention) had no host component, so under the old substring matching *any* URL whose path happened to contain them — e.g. `https://attacker.tld/:generateContent` — was wrongly captured. They're now matched only against the path of requests whose host is already `googleapis.com` or a subdomain of it, and can never match on their own — and only take effect at all if `intercept_addresses` still includes a `googleapis.com` host, so overriding `intercept_addresses` to exclude Google entirely also disables `intercept_path_patterns`.
+- **The default AWS Bedrock entry (`bedrock-runtime`) is now the precise host pattern `bedrock-runtime.*.amazonaws.com`** instead of a bare substring, using new minimal wildcard support in host matching (a single `*` matches exactly one host label). Previously it matched anywhere `"bedrock-runtime"` appeared in a URL, not just the real Bedrock host.
+- **`LoggerService#forward_webhook`'s `response_headers:` option is now redacted like every other header path in the gem.** It was passed straight through to Coolhand unredacted — unlike the sibling `headers:` option — so a caller forwarding a provider webhook alongside its own upstream response (e.g. `forward_webhook(..., response_headers: upstream_response.to_hash)`) shipped that response's `Authorization`/`Set-Cookie`/signature headers to Coolhand in plaintext.
+- **`Coolhand::BaseInterceptor.sanitize_url` now redacts credentials embedded in a URL's userinfo component** (`https://user:pass@host/...`), not just sensitive query parameters. Previously a URL with no query string returned immediately, before userinfo was ever inspected.
+- **`Coolhand::OpenAi::BatchResultProcessor`'s request-log URL is now run through the shared `sanitize_url`**, instead of being forwarded as-is — this path had its own hand-written logging call that predated (and didn't pick up) the shared header/URL sanitization used everywhere else in the gem.
+
+### Dependencies
+- Bumped `json` to 2.21.2, flagged by `bundler-audit` (GHSA-9hj4-r449-hfvc: `JSON::ResumableParser#partial_value` dereferences a freed input buffer on truncated duplicate-key streams). `json` is a transitive dependency (via `rubocop`/`faraday`), not something this gem or its consumers pin directly.
+
 ## [0.5.1] - 2026-08-02
 
 ### Added

data/README.md

@@ -81,6 +81,28 @@ feedback = feedback_service.create_feedback(
 
 For a full field reference and matching strategy, see [Feedback API →](docs/feedback.md).
 
+## Reading Templates
+
+Read back the LLM request templates your logs are matched against. Unlike the logging and feedback methods, these require your **private** API key — the public key is write-only on this API and is rejected exactly like an invalid one.
+
+```ruby
+require 'coolhand'
+
+templates = Coolhand.template_service
+
+result = templates.search_templates(search: 'summar', status: 'published')
+result.templates.each { |template| puts "#{template[:name]} (#{template[:log_count]} logs)" }
+result.pagination.total_count
+
+# Prompt patterns come from a single-template fetch only
+detail = templates.get_template(result.templates.first[:id])
+detail[:user_prompt_pattern]
+```
+
+Search is a parameter on the list endpoint, not a route of its own, and the `Unmatched` / `Ignored API Calls` system buckets are hidden unless you pass `include_system: true`. These are read methods, so they **raise** `Coolhand::HttpError` where the write methods log and return `nil`.
+
+For the full filter reference, pagination, and error handling, see [Reading Templates →](docs/template-search.md).
+
 ## Rails Integration
 
 ### Configuration
@@ -156,7 +178,10 @@ end
 | `enabled` | Boolean | `true` | Set to `false` to disable all patching and validation (e.g. `Rails.env.production?`) |
 | `capture` | Boolean | `true` | Whether to capture and forward intercepted requests. Set to `false` to monitor without forwarding, then use [`Coolhand.with_capture`](#selective-capture) to re-enable selectively |
 | `silent` | Boolean | `false` | Whether to suppress console output |
-| `intercept_addresses` | Array | `["api.openai.com", "api.anthropic.com"]` | Array of API endpoint strings to monitor |
+| `intercept_addresses` | Array | `["api.openai.com", "api.anthropic.com"]` | Array of API hosts to monitor (matched by host, not full URL). This is a required allow-list — `[]` is ignored (a warning is logged) rather than disabling capture; use `enabled` or `capture` for that. See [Configuration](docs/configuration.md) |
+| `intercept_path_patterns` | Array | `[":generateContent", ":streamGenerateContent"]` | Path patterns to additionally monitor on Google API hosts — see [Configuration](docs/configuration.md) |
+| `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) |
 
 ## Usage Examples
 
@@ -315,6 +340,7 @@ The monitor works with multiple transport layers and Ruby libraries:
 - AWS Bedrock (OpenAI-compatible endpoint)
 - Cloudflare AI Gateway
 - OpenRouter
+- OpenCode Zen (`opencode.ai`)
 
 **Universal Coverage**: Since most Ruby HTTP libraries use Net::HTTP under the hood, Coolhand's single interceptor provides comprehensive monitoring without needing library-specific integrations.
 
@@ -400,15 +426,18 @@ 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`) are the exception — they raise `Coolhand::HttpError`; see [Reading Templates →](docs/template-search.md)
 
 ## Documentation
 
 - **[Configuration](docs/configuration.md)** — Self-hosted deployments, base_url rules, debug mode, custom intercept addresses
 - **[Feedback API](docs/feedback.md)** — Full field reference, matching strategies, sentiment values
+- **[Reading Templates](docs/template-search.md)** — Search LLM request templates and fetch a single one, prompt patterns included, using the private API key
 - **[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
 - **[Google Vertex AI Batch Result Logging](docs/vertex.md)** — Log completed Vertex AI batch prediction job results
+- **[Examples](examples/README.md)** — Runnable scripts that make a real provider call through Coolhand, useful as a live smoke test
 
 ## Security
 

data/docs/configuration.md

@@ -39,6 +39,22 @@ end
 
 Because it forces capture unconditionally and prints full request/response bodies to the console, only enable `debug_mode` in development — never in production or in an environment handling real user data.
 
+## Request Body Capture Limits
+
+To avoid holding large uploads (batch JSONL files, fine-tune corpora, audio for transcription) in memory and shipping them to Coolhand in full, `config.max_captured_body_bytes` caps how much of a request body gets captured:
+
+```ruby
+Coolhand.configure do |config|
+  config.max_captured_body_bytes = 2_000_000 # default: 1_000_000 (1 MB)
+end
+```
+
+**What happens at the limits:**
+- A request body whose `Content-Type` doesn't look like JSON (e.g. `multipart/form-data`, `audio/mpeg`) is never read into memory for capture — the log entry gets a placeholder (`{"_coolhand_capture_skipped" => "non_json_content_type", ...}`) instead of the body. This is intentional: an opaque binary blob isn't human/LLM-readable in Coolhand's UI anyway.
+- A JSON (or content-type-unset) body larger than the configured limit is replaced with a placeholder (`{"_coolhand_capture_skipped" => "body_too_large", ...}`) instead of being logged in full.
+
+In both cases, only the *captured log entry* is affected — the real request to the LLM provider always sends the complete, untruncated body.
+
 ## Custom Intercept Addresses
 
 By default Coolhand captures requests to a built-in list of LLM API hosts (OpenAI, Anthropic, Google Gemini, ElevenLabs, GitHub Models, and more). To capture a custom endpoint — an internal proxy, a self-hosted model server, or a third-party gateway — override `intercept_addresses`:
@@ -57,3 +73,27 @@ end
 Setting `intercept_addresses` **replaces** the default list entirely, so include any default hosts you still need.
 
 The default list can be found in `Coolhand::Configuration::DEFAULT_INTERCEPT_ADDRESSES`.
+
+Each entry is matched against the request's parsed host — an exact match, or a dot-boundary suffix match (`my-llm-proxy.internal` also matches `eu.my-llm-proxy.internal`) — case-insensitively. A single `*` in an entry matches exactly one host label, e.g. `bedrock-runtime.*.amazonaws.com`. Entries are never matched against the full URL, so query strings or paths that merely mention a host can't trigger a false match.
+
+A small number of Google API endpoints use a colon-suffixed path (e.g. `.../gemini-pro:generateContent`) with no host of their own. Those live in the separate `intercept_path_patterns` setting (default: `Coolhand::Configuration::DEFAULT_INTERCEPT_PATH_PATTERNS`) and, unlike `intercept_addresses`, are only checked against the path of requests whose host is already `googleapis.com` or a subdomain of it — and only when `intercept_addresses` still includes at least one `googleapis.com` host. If you override `intercept_addresses` to a list with no Google hosts, `intercept_path_patterns` has no effect and Google API traffic is not captured at all.
+
+`intercept_addresses` is a required allow-list — nothing is captured unless its host matches an entry here. Because of that, `config.intercept_addresses = []` is **not** a supported way to disable capture (it's ignored, with a warning logged, and the previous value is kept). To disable capture entirely, use `config.enabled = false` or `config.capture = false` instead — see [Capture Control](#capture-control) below.
+
+## Excluding API Patterns
+
+`config.exclude_api_patterns` is a deny-list checked *after* `intercept_addresses` allows a request through — a match against the request's path is skipped and never forwarded as an `llm_request_log`. It defaults to `["/batchPredictionJobs/"]`, to suppress Vertex AI batch job management noise.
+
+```ruby
+Coolhand.configure do |config|
+  config.exclude_api_patterns << "/myOperationalPath/"    # extend the defaults
+  # config.exclude_api_patterns = ["/only_this/"]          # replace the defaults entirely
+  # config.exclude_api_patterns = []                       # disable exclusion entirely
+end
+```
+
+Unlike `intercept_addresses`, `exclude_api_patterns` genuinely supports `= []` — since it only narrows an allow-list that already passed, an empty deny-list just means "exclude nothing," which is safe.
+
+## Capture Control
+
+`config.enabled` and `config.capture` are the supported ways to turn capture off entirely — see the Configuration Parameters table in the [README](../README.md#configuration-options).

data/docs/openai.md

@@ -58,3 +58,34 @@ def webhook_secret
 end
 # ...existing code...
 ```
+
+## 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`.
+
+Both are configurable:
+
+```ruby
+Coolhand.configure do |config|
+  # Widen or narrow the timestamp tolerance window (seconds). Default: 300.
+  config.webhook_replay_tolerance_seconds = 600
+end
+```
+
+The default `webhook-id` dedup store is in-memory and per-process, so it only protects a single process — replays across multiple app processes/dynos within the tolerance window aren't caught by default. If you run more than one process, supply your own store via `config.webhook_id_store`; any object responding to `claim!(id, ttl_seconds)` works, e.g. one backed by `Rails.cache`. `claim!` must atomically check-and-record the id in one operation (not a separate read then write) — otherwise two requests racing on the same id can both "win" — so lean on your cache backend's compare-and-set primitive (`unless_exist:` below maps to Redis `SET NX` when using `RedisCacheStore`):
+
+```ruby
+class RailsCacheWebhookIdStore
+  # Returns true if this is the first time `id` has been claimed (the
+  # write happened), false if it was already claimed within its TTL.
+  def claim!(id, ttl_seconds)
+    Rails.cache.write("coolhand:openai_webhook:#{id}", true, expires_in: ttl_seconds, unless_exist: true)
+  end
+end
+
+Coolhand.configure do |config|
+  config.webhook_id_store = RailsCacheWebhookIdStore.new
+end
+```
+
+Note: the `webhook-id` is claimed as soon as the signature and timestamp are confirmed valid — before your controller's `process_event` runs. If something downstream fails before the batch is actually handled (e.g. an unexpectedly-shaped payload), a same-id retry within the tolerance window will be rejected as a replay rather than reprocessed.

data/docs/template-search.md

@@ -0,0 +1,218 @@
+# Reading Templates (Search + Get)
+
+`Coolhand::TemplateService` reads back the LLM request templates your logs are matched against.
+It wraps two read-only endpoints:
+
+| method | endpoint |
+|---|---|
+| `search_templates` | `GET /api/v2/llm_request_templates` |
+| `get_template` | `GET /api/v2/llm_request_templates/{id}` |
+
+Both require your **private** API key. The public key is write-only on this API and is rejected
+exactly like an invalid one.
+
+```ruby
+require "coolhand"
+
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_PRIVATE_API_KEY")
+end
+
+templates = Coolhand.template_service
+
+result = templates.search_templates(search: "summar", status: "published")
+result.templates.each { |template| puts "#{template[:name]} (#{template[:log_count]} logs)" }
+
+detail = templates.get_template(result.templates.first[:id])
+puts detail[:user_prompt_pattern]
+```
+
+## What this is not
+
+This is **not** a port of the `search_templates` MCP tool, and the two do not agree:
+
+- `log_count` here counts only directly-collected client logs — the same records
+  `GET /api/v2/llm_request_logs?template_id=…` returns. Evals, bakeoff comparisons and synthetic
+  logs are excluded, so this number is often lower than the MCP tool's.
+- Templates whose workload has been archived are **returned** here, not hidden, so the list agrees
+  with `get_template`, which can always fetch such a template by id. Narrow with `workload_id`
+  instead.
+
+Template *creation, update and deprecation* stay on the MCP surface. This REST surface is
+read-only, and there is no version-history sub-resource.
+
+## `search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil, include_system: nil, page: nil, per: nil)`
+
+Search is a *parameter* on the list endpoint rather than a route of its own, so this is one method
+rather than a list/search pair.
+
+All filters are optional keyword arguments, and their names are the wire names — Ruby's convention
+and this API's already agree, so there is no second spelling to translate through.
+
+| keyword | type | notes |
+|---|---|---|
+| `search` | String | Case-insensitive **literal** substring match on the template name. `%` and `_` are escaped server-side and match themselves — do not escape them again. |
+| `workload_id` | String | Workload hashid. One that does not decode, or that belongs to another client, is a `422` rather than an empty list. |
+| `status` | String | `"draft"`, `"published"` or `"failure"`. Any other non-empty value is a `422` from the server; empty is treated as no filter. |
+| `include_deprecated` | Boolean | Include templates with a non-null `deprecated_at`. Defaults to `false` server-side. |
+| `include_system` | Boolean | Include the `Unmatched` / `Ignored API Calls` buckets. Defaults to `false` server-side. |
+| `page` | Integer | 1-based. |
+| `per` | Integer | Default 25, max 100, both enforced server-side. |
+
+Two things it deliberately does **not** do:
+
+- **There is no `client_id` keyword.** The client is always derived from the authenticating API key
+  and cannot be supplied, so passing one raises `ArgumentError` rather than reaching the wire.
+- **`status` is not checked against a client-side allowlist.** The API definition enumerates the
+  values on the *query parameter*, but leaves the `status` field on the *response* an unconstrained
+  string. Sending an unrecognised value gets you the server's `422`; a status the server gains
+  later works without a gem release.
+
+`per_page` is accepted on the wire as an alias for `per`. This gem only ever sends `per` — one knob
+is enough.
+
+### Return value
+
+A `Coolhand::TemplateSearchResult` — a `Struct`, so `#templates`, `#pagination`, `#to_h` and
+pattern matching all work:
+
+```ruby
+result = Coolhand.template_service.search_templates(include_system: true)
+
+result.templates   # => [{ id: "kp9npvc8qq2q", name: "Unmatched", ... }, ...]
+result.pagination  # => #<struct Coolhand::Pagination current_page=1, ...>
+```
+
+**Rows are plain Hashes with Symbol keys**, the same shape `create_feedback` and `create_log`
+already return. They are handed back exactly as the API rendered them rather than being copied into
+a value object, so a field the server adds later reaches you instead of being silently dropped on
+the way through. That is also why there is no `system_template?` predicate: read the wire field,
+`template[:system_template]`.
+
+Rows are ordered newest first (`created_at DESC`, with a primary-key tiebreaker so paging is stable
+across requests). Each carries:
+
+| field | type | notes |
+|---|---|---|
+| `:id` | String | Hashid, never the integer primary key. |
+| `:name` | String | Never null, but may be blank on a draft. |
+| `:status` | String or nil | `draft` / `published` / `failure`. |
+| `:version` | String or nil | |
+| `:group` | String or nil | `chat`, `user_prompt`, `user_prompt_with_system_prompt`, `embedding`, `other`. |
+| `:workload_id` | String | Workload hashid; never null. |
+| `:workload_name` | String | Never null. |
+| `:system_template` | Boolean | True for the `Unmatched` / `Ignored API Calls` buckets. |
+| `:deprecated_at` | String or nil | ISO-8601 UTC. Non-null means the template has been superseded. |
+| `:log_count` | Integer | Directly-collected client logs only — see [What this is not](#what-this-is-not). |
+| `:created_at` | String | ISO-8601 UTC. |
+| `:updated_at` | String | ISO-8601 UTC. |
+
+**Prompt patterns are not in the list.** They come from `get_template` only.
+
+`pagination` is a `Coolhand::Pagination` built from the endpoint's `X-Page`, `X-Per-Page`,
+`X-Total-Count` and `X-Total-Pages` response headers — never from the size of the array, which only
+ever describes the page in hand. Unlike `/llm_request_logs` there is no `include_total` opt-out
+here; the headers are always sent.
+
+| field | type |
+|---|---|
+| `current_page` | Integer |
+| `per_page` | Integer |
+| `total_count` | Integer |
+| `total_pages` | Integer |
+| `has_next_page` | Boolean |
+| `has_prev_page` | Boolean |
+
+### System templates and the empty default list
+
+Every Coolhand client is created with two system buckets, `Unmatched` and `Ignored API Calls`. They
+are hidden unless you pass `include_system: true`, so a client with no templates of its own gets an
+empty array rather than those two rows. `Unmatched` is what you inspect when logs are misrouting:
+
+```ruby
+unmatched = Coolhand.template_service
+                    .search_templates(include_system: true, search: "unmatched")
+                    .templates
+                    .first
+
+puts unmatched[:log_count]
+```
+
+## `get_template(id)`
+
+`id` is the template hashid — the `:id` field from `search_templates`.
+
+Returns a Hash with every list field above, **plus** the full untruncated regexes the list omits:
+
+| field | type |
+|---|---|
+| `:user_prompt_pattern` | String or nil |
+| `:system_prompt_pattern` | String or nil |
+
+Unlike the list, this filters on nothing but client ownership: a deprecated or system template is
+reachable by id with **no opt-in flag**, because inspecting one of those is the usual reason to
+fetch a template directly.
+
+## Errors
+
+The write methods in this gem (`create_feedback`, `create_log`, `send_llm_request_log`) log a
+failure and return `nil` — instrumentation must never be the reason a host app falls over. **The
+read methods are the opposite and raise**, because a caller that asked for data has to be able to
+tell a `404` from a timeout from a genuinely empty result.
+
+| raised | when |
+|---|---|
+| `Coolhand::HttpError` | The server answered with a non-2xx status. `#status` is the HTTP status code and `#body` the response body. |
+| `Coolhand::Error` | No API key configured, a transport failure, a body that is not valid JSON, or a blank `id` passed to `get_template`. |
+
+`Coolhand::HttpError` is a `Coolhand::Error`, so `rescue Coolhand::Error` catches both.
+
+**Branch on `#status`, never on the message:**
+
+```ruby
+begin
+  result = Coolhand.template_service.search_templates
+rescue Coolhand::HttpError => e
+  case e.status
+  when 401 then warn "Private API key required — the public key cannot read"
+  when 422 then warn "Bad filter: #{e.body}"
+  when 504 then warn "Timed out aggregating log_count — narrow the query and retry"
+  else raise
+  end
+end
+```
+
+| status | meaning |
+|---|---|
+| `401` | Missing, invalid, or public API key. |
+| `404` | `get_template` only. Unknown id, **or** one belonging to another client — existence is not disclosed, so this is never a `403`. |
+| `422` | Unrecognised `status`, or a `workload_id` that does not decode or belongs to another client. |
+| `504` | See below. |
+
+### `504` is expected, and retryable
+
+`log_count` aggregates over `llm_request_logs`, so its cost scales with how many logs the matched
+templates hold — the `Unmatched` bucket can hold every log that never matched a template. Every
+query behind these responses is bounded by a 10-second statement timeout, and exceeding it returns
+`504` rather than hanging. It reaches you as an `HttpError` with `status == 504`, not folded into a
+generic server error, precisely so you can narrow and retry:
+
+```ruby
+templates = Coolhand.template_service
+
+begin
+  templates.search_templates(include_system: true)
+rescue Coolhand::HttpError => e
+  raise unless e.status == 504
+
+  # Narrow the aggregate: one workload at a time, smaller pages.
+  templates.search_templates(include_system: true, workload_id: workload_id, per: 10)
+end
+```
+
+This is also why the read path waits far longer than the write path before giving up. A write
+times out after 5 seconds because it runs inline in your app's own request. A read allows 60: the
+server bounds each *statement* behind a response at 10 seconds, but one response runs several, so
+a slow-but-working `include_system=true` call measured 7-15 seconds against a development database
+while returning `200` every time. Giving up sooner would report a working endpoint as a transport
+failure, and would pre-empt the `504` you are meant to see and retry.