coolhand 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daed2b7ac4fe321602eb90f673cb385bd930b9ff503bf7e5d7851cbf06422617
-  data.tar.gz: 5d01a6386d142cdb31c490574191ac3867dabd30670c2a832c2aa18c7150c872
+  metadata.gz: a3c1e767ea245f56520ee634e48cd2f12c6dc06be79b3998537fea9e9b8ea9ff
+  data.tar.gz: aad0485d474aa1e3f796f2af30083304a1ed704ede8428ddc4b0c9a4ff32678e
 SHA512:
-  metadata.gz: a0681a3419c92e13fbae7a1b81c6d81b7a1cf2f088571dd44b4d2694c0ae5bf5c4c4312d7bff53ccc740833290bc931b932c1179244f004090192b0baaeb19f0
-  data.tar.gz: 9efd5e33528e0caeecc770c7286085320f9e4218f01fcf592ca82a27c96df71cf5ae52712a5a9aaeaf0702774be450bb7c3b7c71b0df8e57f56bd038f54f1b3d
+  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,70 @@ 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
+- **`Coolhand::Vertex::BatchResultProcessor.new` accepts an optional `model:` keyword** (falls back to a `"model"` key in `batch_info` when omitted) to populate the `model` field on batch-result logs — included only when one of those is available and non-blank, and omitted from the payload entirely otherwise (#76).
+- **`Coolhand::BaseInterceptor.send_complete_request_log` accepts optional `source_api:`/`model:` keywords**, for synthetic/batch log types (like the Vertex processor above) that aren't backed by a real intercepted HTTP request (#76).
+
+### Changed
+- **Vertex batch results with a missing or malformed job resource name or unparseable `startTime`/`endTime` are no longer logged at all.** Previously the processor still sent a request log using whatever was in `batch_info["name"]` (even if blank), just with a broken URL. It now validates these fields and skips the log entirely — with a `Rails.logger.error` explaining why — rather than sending something unusable (#76).
+- **A batch whose `endTime` precedes its `startTime` (e.g. clock skew) is still logged**, with `duration_ms` clamped to `0` and a warning logged, rather than dropped — unlike the missing/malformed cases above, the request/response content itself is still valid here (#76).
+- **A Vertex batch result item that isn't a `Hash` with a `"request"` and/or `"response"` key is now rejected and logged as an error**, instead of being sent as a log with `nil` request/response bodies (#76).
+- **The published gem no longer packages `.claude/`, `.idea/`, or `CLAUDE.md`** — these are repo/agent tooling, not part of the library.
+
+### Security
+- **A webhook processing error no longer leaves the request authenticated by default.** `Coolhand::WebhookInterceptor#intercept_batch_request` previously logged and swallowed *any* exception (a malformed webhook secret, a non-Hash JSON payload, a bug in `process_event`), returning normally without halting the Rails `before_action` chain — so the controller action still ran for a request whose signature was never confirmed valid. It now calls `head :unauthorized` in that rescue, matching the existing invalid-signature path, and validates the parsed webhook payload is a `Hash` before use.
+- **A blank or whitespace-only OpenAI webhook secret is no longer usable as the HMAC key.** `Coolhand::OpenAi::WebhookValidator` previously only rejected `nil`/`false`, so `webhook_secret = ""` (e.g. an unset `ENV` var with a blank default) silently signed and verified requests with an empty key — a much weaker, easy-to-guess bypass than the already-known "secret not configured" path. It now uses the same `Coolhand.required_field?` blank-check used elsewhere in the gem.
+- **`Cookie`/`Set-Cookie` headers are now redacted**, alongside the existing key/token/secret/signature/authorization patterns. Forwarding a Rails session cookie (a bearer credential) to Coolhand — e.g. via `LoggerService#forward_webhook(headers: request.headers)`, the pattern this gem's own docs show — was previously possible.
+- **`BaseInterceptor.sanitize_url` now redacts a broader set of credential-shaped query parameters** (`sig`, `credential`, `password`, `auth`, in addition to the existing `key`/`token`/`secret`), matching the pattern-based approach already used for headers instead of a small exact-match list. This covers AWS SigV4 (`X-Amz-Signature`, `X-Amz-Credential`) and Google Cloud (`X-Goog-Signature`, `X-Goog-Credential`) presigned-URL parameters that were previously logged in full.
+- **A failure capturing an intercepted request's body (e.g. an already-consumed `body_stream`) no longer prevents the real request from being attempted.** The capture happened before any error handling was in place, so an exception there escaped `NetHttpInterceptor#request` entirely — the host app's actual LLM call never happened. It's now rescued, logged, and treated as "body unavailable," and the real request still proceeds.
+- **Streamed response bodies are no longer buffered into a thread-local for requests this gem never intercepted.** `ResponseInterceptor#read_body` previously buffered every block-form `read_body` call process-wide, regardless of whether the enclosing request matched `intercept_addresses` — an unbounded memory growth path on any thread that streams large non-LLM responses (file downloads, etc.). Buffering now only happens while a `NetHttpInterceptor#request` call is actively capturing.
+- **A request made from inside another intercepted request's streaming callback no longer corrupts the outer request's logged response body.** The per-thread stream buffer is now saved and restored around each intercepted request instead of unconditionally cleared, so nested/reentrant LLM calls (e.g. a second provider call triggered from a chunk handler) no longer mix one request's content into another's log entry.
+- **Coolhand's own request to its backend API is no longer re-intercepted and re-logged.** If a self-hosted `base_url` or custom `intercept_addresses` entry happens to match Coolhand's own API host, the log-shipping request itself would previously be captured and logged like any other request — which itself gets logged, recursively, without bound. It's now wrapped in `Coolhand.without_capture`.
+- `Coolhand::OpenAi::WebhookValidator#webhook_secret` is no longer a public reader (it's only used internally) — reduces the chance of the raw secret ending up in error-tracker breadcrumbs or view-rendered controller state.
+- `YAML.load_file` → `YAML.safe_load_file` for the gem's own bundled default-addresses/patterns YAML files — defense-in-depth against unsafe deserialization, consistent with modern Psych defaults.
+- Added missing `require "openssl"` (`WebhookValidator`) and `require "stringio"` (`NetHttpInterceptor`) instead of relying on both being transitively loaded by something else first.
+
+### Fixed
+- **Vertex batch result logging** — `Coolhand::Vertex::BatchResultProcessor` now sends a fully-qualified URL (`https://aiplatform.googleapis.com/v1/<resource name>`) instead of the bare Vertex job resource name, plus explicit `source_api` and `model` values, all inside `raw_request`. The Coolhand API treats `raw_request` as free-form JSON, so this improves the data available to its classification without depending on new top-level payload fields being accepted. Also fixed: `timestamp`/`completed_at` are now sent as proper ISO 8601 strings instead of raw `Time` objects, and the URL is now run through the same `sanitize_url` helper used by every other logging path in the gem, for consistency (a Vertex batch URL can't actually carry a redactable query string today, so this is defense-in-depth rather than a fix for a live leak) (#76).
+- **`require "coolhand"` no longer requires `faraday`.** The gem hasn't used Faraday directly since the 0.4.0 unified `NetHttpInterceptor`, but a stale top-level `require "faraday"` meant loading the gem could raise `LoadError` for anyone without faraday installed — it was never a declared dependency. If your app relied on `require "coolhand"` transitively loading Faraday, require it yourself.
+- `Coolhand::Vertex::BatchResultProcessor`, `Coolhand::OpenAi::BatchResultProcessor`, and `Coolhand::OpenAi::WebhookValidator` can now each be required independently (e.g. `require "coolhand/vertex/batch_result_processor"`) without first requiring `"coolhand"` — previously this could raise `NameError` depending on load order.
+- `Coolhand::BaseInterceptor.send_complete_request_log` now runs `request_headers`/`response_headers` through `sanitize_headers` itself, rather than trusting every caller to have pre-sanitized them. `NetHttpInterceptor` already sanitized before calling it (`sanitize_headers` is idempotent, so no behavior change there); this closes the gap for any future caller that forgets.
+- `Coolhand::Vertex::BatchResultProcessor#handle_failed_batch` no longer raises `NoMethodError` when a failed batch's `error` field is missing or not a Hash — it now logs the batch-failure message either way instead of falling through to the generic "failed to process" catch-all.
+- **README's "Request Flow" section corrected** — it previously claimed data is sent to the Coolhand API "asynchronously in a background thread" with "zero performance impact"; it's actually sent inline, after the original response is available, bounded by the 5-second timeout described in 0.5.0's Security section.
+
 ## [0.5.0] - 2026-07-30
 
 ### Changed

data/README.md

@@ -39,14 +39,14 @@ end
 # ✅ OpenAI SDK calls
 # ✅ Anthropic API calls
 # ✅ Direct HTTP requests to AI APIs
-# ✅ ANY library making AI API calls via Faraday
+# ✅ Any library making AI API calls via Faraday's default adapter
 
 # NO code changes needed in your existing services!
 ```
 
 **✨ Why Automatic Monitoring:**
 - 🚫 **Zero refactoring** - No code changes to existing services
-- 📊 **Complete coverage** - Monitors ALL AI libraries using Faraday automatically
+- 📊 **Complete coverage** - Monitors AI libraries using Net::HTTP or Faraday's default adapter automatically
 - 🔒 **Security built-in** - Automatic credential sanitization
 - ⚡ **Performance optimized** - Negligible overhead via async logging
 - 🛡️ **Future-proof** - Automatically captures new AI calls added by your team
@@ -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
 
@@ -297,19 +322,26 @@ The filtering is automatic and applies to all monitored API calls and webhook lo
 
 The monitor works with multiple transport layers and Ruby libraries:
 
-**Faraday-based libraries:**
+**Faraday-based libraries** (via Faraday's default `net_http` adapter — a non-Net::HTTP adapter such as `faraday-typhoeus` is not covered):
 - OpenAI Ruby SDK
 - ruby-anthropic gem (community Anthropic gem)
 - ruby-openai gem
 - LangChain.rb
-- Direct Faraday requests
-- Any other Faraday-based HTTP client
+- Direct Faraday requests using the default adapter
 
 **Native HTTP libraries:**
 - Official Anthropic Ruby SDK (using Net::HTTP)
 - GitHub Models SDK / any client using `models.github.ai`
 - Any library using Net::HTTP directly
 
+**Other providers monitored out of the box:**
+- Google Gemini (`generativelanguage.googleapis.com`)
+- Google Vertex AI (`aiplatform.googleapis.com`) — see the [Vertex AI batch result logging guide](docs/vertex.md) for async batch jobs
+- 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.
 
 ## How It Works
@@ -325,11 +357,11 @@ Coolhand uses a unified Net::HTTP interceptor to capture outgoing requests to co
 ### Request Flow
 When a request matches configured LLM endpoints:
 
-1. The original request executes normally with zero performance impact
+1. The original request executes normally
 2. Request and response data (body, headers, status) are captured by the interceptor
 3. For streaming requests, the complete accumulated response is captured (not individual chunks)
-4. Data is sent to the Coolhand API asynchronously in a background thread
-5. Your application continues without interruption
+4. Data is sent to the Coolhand API inline, after the original response is available (bounded by a 5-second connect/read timeout so a slow or unreachable Coolhand backend can't hang your request indefinitely)
+5. Your application continues once the log is sent (or times out) — the original request/response is never blocked on Coolhand being reachable
 
 For non-matching endpoints, requests pass through unchanged.
 
@@ -394,109 +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
-
-
-## Batch webhook handler (OpenAI)
-
-Automatically handle OpenAI batch event logs (batch.completed, batch.failed, batch.expired, batch.cancelled)
-by intercepting webhook requests and enqueuing your batch result processor.
-
-Usage:
-- Include the interceptor in your controller:
-  include Coolhand::WebhookInterceptor
-- Add the before_action to validate and populate @validator payload:
-  before_action :intercept_batch_request, only: :openai
-- Ensure you skip CSRF for the webhook endpoint:
-  skip_before_action :verify_authenticity_token
-- Override the webhook_secret method to return your OpenAI webhook secret
-
-Minimal example (only key lines shown):
-
-```ruby
-# app/controllers/webhooks/batch_api_requests_controller.rb
-# ...existing code...
-include Coolhand::WebhookInterceptor
-
-skip_before_action :verify_authenticity_token
-before_action :intercept_batch_request, only: :openai
-
-def openai
-  event = JSON.parse(@validator.payload)
-  case event["type"]
-  when "batch.completed", "batch.failed", "batch.expired", "batch.cancelled"
-    batch_id = event.dig("data", "id")
-    batch_request = BatchApiRequest.find_by(provider: "openai", provider_batch_id: batch_id)
-
-    if batch_request
-      OpenAi::BatchResultProcessor.perform_async(batch_request.id)
-      Rails.logger.info("Queued batch result processing for BatchApiRequest #{batch_request.id}")
-    else
-      Rails.logger.warn("Could not find BatchApiRequest for OpenAI batch ID: #{batch_id}")
-    end
-  else
-    Rails.logger.info("Unhandled OpenAI webhook event type: #{event["type"]}")
-  end
-
-  head :ok
-rescue JSON::ParserError
-  head :bad_request
-rescue StandardError => e
-  Rails.logger.error("OpenAI webhook error: #{e.message}")
-  head :internal_server_error
-end
-
-def webhook_secret
-  Rails.application.credentials.openai_webhook_secret
-end
-# ...existing code...
-```
-
-## Batch webhook handler (Vertex)
-
-Automatically handle Vertex batch event logs.
-
-Usage:
-- call Coolhand::Vertex::BatchResultProcessor service with batch_info and download batch results
-
-Minimal example (only key lines shown):
-
-```ruby
-class Vertex::BatchCallbackProcessor < BaseService
-  option :batch_request, model: BatchApiRequest
-  option :batch_info
-
-  def call
-    case batch_info["state"]
-    when "JOB_STATE_PENDING"
-      nil
-    when "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
-      batch_request.update!(status: "processing")
-
-      Coolhand::Vertex::BatchResultProcessor.new(batch_info:).call
-    when "JOB_STATE_SUCCEEDED"
-      output_file_id = batch_info["outputInfo"]["gcsOutputDirectory"]
-      results = download_batch_results(output_file_id)
-      results.each { |batch_item| process_batch_result(batch_item) }
-
-      batch_request.update!(status: "completed", completed_at: Time.current, output_file_id:)
-
-      Coolhand::Vertex::BatchResultProcessor.new(batch_info:).call(results)
-
-      # Clean up GCS files after successful processing
-      cleanup_gcs_files(output_file_id)
-    when "JOB_STATE_FAILED"
-      handle_failed_batch(batch_info["error"]["message"])
-    end
-  end
-end
-```
+- 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

@@ -0,0 +1,91 @@
+# OpenAI Batch Webhook Handler
+
+Automatically handle OpenAI batch event logs (`batch.completed`, `batch.failed`, `batch.expired`, `batch.cancelled`) by intercepting webhook requests and logging completed batch results to Coolhand.
+
+For monitoring regular (non-batch) OpenAI API calls, see the [OpenAI client example](../README.md#with-openai-ruby-client) in the main README — no extra setup is required beyond `Coolhand.configure`.
+
+Requires Rails — `Coolhand::WebhookInterceptor` and `Coolhand::OpenAi::BatchResultProcessor` log via `Rails.logger` internally. `config.capture = false` and `Coolhand.without_capture` do not suppress these logs: unlike the passive Net::HTTP interceptor, `intercept_batch_request` dispatching to `Coolhand::OpenAi::BatchResultProcessor` is an explicit, deliberate act, so it always sends.
+
+## Usage
+
+- Add the `openai` gem to your Gemfile — `Coolhand::OpenAi::BatchResultProcessor` needs it to download batch result files.
+- Include the interceptor in your controller: `include Coolhand::WebhookInterceptor`
+- Add the `before_action` to validate and populate the `@validator` payload: `before_action :intercept_batch_request, only: :openai`
+- Ensure you skip CSRF for the webhook endpoint: `skip_before_action :verify_authenticity_token`
+- Override the `webhook_secret` method to return your OpenAI webhook secret
+
+`intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` **synchronously**, inline in the `before_action` — that part requires no code in your controller action. It downloads two JSONL files from OpenAI and sends one request log per batch item, so a large batch can take long enough to trip your webhook endpoint's timeout (and OpenAI's retry behavior); consider that when sizing batches. The example below shows a controller action doing additional, app-specific work on top of that (e.g. updating your own `BatchApiRequest` record and enqueuing your own background job), which is optional.
+
+## Minimal example
+
+Only the key lines are shown — wire this into your own controller and background job setup.
+
+```ruby
+# app/controllers/webhooks/batch_api_requests_controller.rb
+# ...existing code...
+include Coolhand::WebhookInterceptor
+
+skip_before_action :verify_authenticity_token
+before_action :intercept_batch_request, only: :openai
+
+def openai
+  event = JSON.parse(@validator.payload)
+  case event["type"]
+  when "batch.completed", "batch.failed", "batch.expired", "batch.cancelled"
+    batch_id = event.dig("data", "id")
+    batch_request = BatchApiRequest.find_by(provider: "openai", provider_batch_id: batch_id)
+
+    if batch_request
+      MyApp::BatchResultJob.perform_async(batch_request.id)
+      Rails.logger.info("Queued batch result processing for BatchApiRequest #{batch_request.id}")
+    else
+      Rails.logger.warn("Could not find BatchApiRequest for OpenAI batch ID: #{batch_id}")
+    end
+  else
+    Rails.logger.info("Unhandled OpenAI webhook event type: #{event["type"]}")
+  end
+
+  head :ok
+rescue JSON::ParserError
+  head :bad_request
+rescue StandardError => e
+  Rails.logger.error("OpenAI webhook error: #{e.message}")
+  head :internal_server_error
+end
+
+def webhook_secret
+  Rails.application.credentials.openai_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.