coolhand 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3c1e767ea245f56520ee634e48cd2f12c6dc06be79b3998537fea9e9b8ea9ff
-  data.tar.gz: aad0485d474aa1e3f796f2af30083304a1ed704ede8428ddc4b0c9a4ff32678e
+  metadata.gz: 256c9237619b3f7116aa9751f78f0d0e367381b12afa694742da07ed1d7d3123
+  data.tar.gz: 149ddf8c4cd1800b105382ade5d2a2e9e57a360884e34e1b988b926739e90f30
 SHA512:
-  metadata.gz: 2b497e1401c64e9eb6a6b1bbb061ecb359985a39f8dd95ce8018406d36e3c49ba061e5557299d4e6ee00498f8f8bf91ac9f3b91e56a32f5b08af599f5ef16768
-  data.tar.gz: 84d13bff930f045607270849ad02fd5c8548b15b39f2043636c868bcfe857e04fab4c0ae113fe4e5872ca299d197c83b04c2f0adce5bffe3723c4bacd5890b03
+  metadata.gz: 2ccbf54c2787a8df93178120583d83666553454a1b86385ec1c4ea10e228b859b995a35bed1450e9ab6d38dbb5d145d9b7a269be89f5562870d51a63630e5653
+  data.tar.gz: 4e6db88c4530737370030809a9d8e094d791761a6306a63701edc4413ed81f61a716d975953799c3d46b0cebbb3ddd9e1d172b22ee5d7b29c18bdd65ffe9e25c

data/AGENTS.harness.md

@@ -39,8 +39,8 @@ node <workspaceRoot>/coolhand/harness/harness.mjs my-issue --run <RUN_DIR> --rep
 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.
+4. `coolhand-ruby/AGENTS.md` — this repo's own rulebook. **It is authoritative.** Where it
+   disagrees with this harness file, AGENTS.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
@@ -70,7 +70,7 @@ inside the current architecture, escalate and STOP.
 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`.
+dependencies. See `coolhand-ruby/AGENTS.md`.
 
 ## 3. Prove it against the real server
 
@@ -107,13 +107,44 @@ node <workspaceRoot>/coolhand/harness/harness.mjs wait --run <RUN_DIR> --channel
 
 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.
+## 5. Get your review — you cannot run it yourself
+
+**Mandatory, before you push. You do not run this section yourself.** You are three
+levels deep in this tree (server → node → you), and the platform does not let an agent at
+this depth spawn the reviewer subagent the review skill needs — see
+`<workspaceRoot>/coolhand/harness/RESIST_RULES.md` → R8's depth table. This is not something
+to confirm by trying; go straight to the request below.
+
+1. Commit locally first — build, prove it against the local server, run `bundle exec rake`,
+   all of section 3, all done before this step.
+2. Send an R8 escalation to node naming your repo path, branch, and `HEAD` sha:
+   ```
+   node <workspaceRoot>/coolhand/harness/harness.mjs send --run <RUN_DIR> --channel ruby \
+     --from ruby --to node --kind escalation \
+     --text "R8: ready for review. repo=<workspaceRoot>/coolhand-ruby branch=<branch> sha=<sha>"
+   ```
+3. `wait --after` the `messageId` your `send` in step 2 just printed. A timeout is silence,
+   not permission — call `wait` again, `--after` that same id, rather than pushing
+   (`RESIST_RULES.md` → "What escalate and stop means, mechanically"). If you loop back here
+   from step 5, use the fresh escalation's `messageId` instead.
+4. **The first reply is an `ack`, not the answer** — it means node has started, not that it
+   is done. `wait` again, `--after` that ack's `messageId`, for the `resolution` that
+   actually follows.
+5. **If what follows is a second `ack` instead of a `resolution`, node is asking you to do
+   something before it can start — most often that your checkout is not clean** (see
+   `RESIST_RULES.md` → R8 → "Serving a review for a child" step 2). Do what it asks, then
+   send a fresh R8 escalation with your current `HEAD` sha (it may have changed) and go back
+   to step 3. Do not just `wait` again — nothing arrives until you re-escalate.
+6. **The `resolution` that eventually arrives always carries the full Iteration Breakdown
+   table plus an explicit `CLEAN`/`capped` verdict** — the same `result` value node has
+   already recorded (it records before it replies) — from a review node ran against your
+   actual repo. Not just one or the other, not your own read of the diff, and not an ack.
+   This is what you post as your own PR comment below, unedited plus the "Reviewed by node
+   against `<sha>`" line.
+7. **Then move on to section 6 (Open your PR).** If node's review applied fixes,
+   it already committed them directly into your checkout while you waited — whatever is at
+   `HEAD` when you push there already includes them, and you do not need to reproduce or
+   look for them separately.
 
 ## 6. Open your PR — then STOP
 
@@ -123,8 +154,11 @@ for, escalate to node (R8) and STOP rather than substitute a self-review.
 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."
+4. Post node's Iteration Breakdown table (section 5) as a comment on this PR — see
+   `RESIST_RULES.md` → "After the loop exits" — and add one line the table itself does not
+   carry: `Reviewed by node against <sha>`, since you did not run it yourself. **Do not call
+   `harness.mjs loop-review` here — node already recorded it**, against the sha that
+   resulted from its own fix commits, not the one you originally escalated with.
 5. **Stop.** You launch no one. The tree ends with you on this branch.
 
 ## 7. Done means
@@ -133,7 +167,8 @@ for, escalate to node (R8) and STOP rather than substitute a self-review.
 - [ ] `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
+- [ ] Node ran your review for real (not approximated by you) and its Iteration Breakdown
+      table is posted as a comment on your PR, naming node and the reviewed sha, and
+      recorded with `harness.mjs loop-review`
 - [ ] 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,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-09
+
+### Added
+- **Read workloads and logs, with cost and performance metrics** ([#138](https://github.com/Coolhand-Labs/coolhand-ruby/pull/138)) — `Coolhand.workload_service.search_workloads` lists workloads (`GET /api/v2/workloads`) and `Coolhand.log_service` reads logs back out: `search_logs` (filters including `since`, `until`, `min_cost`, `order`, `project_path`, `source_application`, `include_total`, `sort`) and `get_log`, which returns `cost` and `cost_breakdown`. `search_templates` and `get_template` gain `include_metrics`, `days_back`, `since` and `until`. `since:`/`until:` accept a `Time`, `DateTime`, `Date` or ISO8601 String; anything else raises `ArgumentError` before a request is made. These need your **private** API key and raise `Coolhand::Error` (`Coolhand::HttpError` for non-2xx responses) rather than logging and returning `nil`. **Deploy note:** requires the matching Coolhand server release (Coolhand-Labs/coolhand#1753). See [Reading Workloads](docs/workload-search.md) and [Reading Logs](docs/log-search.md).
+- **Link feedback to an optimization** ([#133](https://github.com/Coolhand-Labs/coolhand-ruby/pull/133)) — `Coolhand.optimization_feedback_link_service` provides `link_feedback`, `bulk_link_feedback` (sent in batches of 100, results summed) and `unlink_feedback` for `/api/v2/optimizations/:id/feedback_links`. Private API key required; failures raise `Coolhand::Error` / `Coolhand::HttpError`. See [Linking Feedback](docs/feedback-links.md).
+- **Logs are sent from a background queue by default** ([#148](https://github.com/Coolhand-Labs/coolhand-ruby/pull/148)) — the Coolhand POST no longer runs inline in the intercepted LLM call, so a slow or unreachable Coolhand backend can no longer add up to about 10s to each call. `Coolhand::LogQueue` holds up to 1,000 jobs per lane and drops the oldest when full, restarts itself in forked processes, and flushes at exit (waiting up to 5s). OpenAI and Vertex batch results are processed as one background job per batch, on their own lane so a long batch cannot delay or evict per-request logs. New `config.async_logging` (default `true`) and `Coolhand.flush(timeout: 5)`; `examples/benchmark_async_logging.rb` is a pass/fail benchmark. See [Asynchronous Logging](docs/configuration.md#asynchronous-logging). **Migration note:** anything that relied on the log POST finishing before the intercepted call returned (tests asserting on a stubbed `ApiService` inline, scripts that end with `exit!`, a process killed by `kill -9` or the OOM killer, which loses queued logs) should set `config.async_logging = false` or call `Coolhand.flush`. `debug_mode` always runs inline.
+
+### Changed
+- Repo guidance moved from `CLAUDE.md` to `AGENTS.md` ([#130](https://github.com/Coolhand-Labs/coolhand-ruby/pull/130)), and the agent-harness review handshake in `AGENTS.harness.md` was rewritten ([#134](https://github.com/Coolhand-Labs/coolhand-ruby/pull/134)). Neither ships in the gem, and `AGENTS.md` is excluded from the gem package in place of `CLAUDE.md`.
+- CI now uses `ruby/setup-ruby` 1.327.0 ([#135](https://github.com/Coolhand-Labs/coolhand-ruby/pull/135)).
+- Shared read-URL building moved into `Coolhand::ReadQuery`, and POST/DELETE helpers that raise on failure into `Coolhand::WriteRequests`; `TemplateService` now uses `ReadQuery`. Internal refactor with no behavior change to `search_templates`/`get_template` beyond the new options.
+- `Coolhand::NetHttpInterceptor` no longer includes `BaseInterceptor` ([#148](https://github.com/Coolhand-Labs/coolhand-ruby/pull/148)); its helpers moved to `Coolhand::NetHttpInterceptor::Helpers`, so `Net::HTTP` gains only `#request` instead of about 15 generically named private methods (`intercept?`, `parse_json`, `sanitize_url`, ...). **Migration note:** internal API, but if you called those helpers on a `Net::HTTP` instance, use `Coolhand::NetHttpInterceptor::Helpers` or `Coolhand::BaseInterceptor`.
+
+### Fixed
+- Disabling the Net::HTTP interceptor logged a stale "Faraday monitoring disabled" message ([#148](https://github.com/Coolhand-Labs/coolhand-ruby/pull/148)); it now says "Net::HTTP interceptor unpatched (capture stopped)".
+
+### Security
+- **Release-time hardening from a whole-package security review** ([#148](https://github.com/Coolhand-Labs/coolhand-ruby/pull/148), plus fixes made on the release branch):
+  - Requests forwarded by the OpenAI batch webhook handler now go through the same request-body redaction as live interception, so Azure OpenAI "On Your Data" datastore credentials in a batch request body are replaced with `[REDACTED]` before being sent to Coolhand.
+  - The OpenAI batch handler now matches requests to results with a one-pass index instead of a scan per result, so a large batch no longer takes quadratic time. When a `custom_id` is duplicated the first request still wins, as before.
+
+## [0.7.0] - 2026-09-20
+
+### Added
+- **Seven more providers are monitored out of the box** ([#117](https://github.com/Coolhand-Labs/coolhand-ruby/pull/117)) — DeepSeek (`api.deepseek.com`), Mistral (`api.mistral.ai`), Perplexity (`api.perplexity.ai`) and xAI (`api.x.ai`) are captured host-wide. Cohere is captured only on its chat and embed endpoints (`/v2/chat`, `/v1/embed`, `/v2/embed`, on `api.cohere.com` and `api.cohere.ai`), TypeSafe Jev only on `api.typesafe.ai/v1/systemone`, and Ollama only on port 11434 for `/api/chat`, `/api/generate`, `/api/embed` and `/api/embeddings` (`localhost`, `127.0.0.1`, or a bare single-label host such as a Docker Compose service). No configuration required. **Migration note:** if your app already calls any of these, those calls will now start being logged to Coolhand after upgrading. To opt out, override `config.intercept_addresses` with your own list.
+- **Azure inference endpoints are monitored out of the box** ([#115](https://github.com/Coolhand-Labs/coolhand-ruby/pull/115)) — Azure OpenAI dedicated hosts (`openai.azure.com`/`.us`/`.cn`), Azure AI Services / Foundry multi-service hosts (`cognitiveservices.azure.*`, `services.ai.azure.*`, captured only on their `/openai/` and `/models/` paths), serverless/MaaS hosts (`inference.ai.azure.com`, `models.ai.azure.com`) and Azure ML managed online endpoints (`inference.ml.azure.com`/`.us`). The Azure ML entries are deliberately not path-anchored, because every managed online endpoint scores at `/score`, so non-LLM deployments there will also be captured. Remove those two entries from `intercept_addresses` if that over-captures for you. Default `exclude_api_patterns` now also skips Azure OpenAI control-plane paths (`/openai/files`, `/batches`, `/fine_tuning`, `/models`, and their `/openai/v1/` spellings). **Migration note:** anyone who set `exclude_api_patterns` explicitly keeps their own list and will not get the new Azure exclusions.
+- **`intercept_addresses` entries can pin a port and/or a path prefix** ([#117](https://github.com/Coolhand-Labs/coolhand-ruby/pull/117), [#115](https://github.com/Coolhand-Labs/coolhand-ruby/pull/115)) — `host:port`, `host/path` and `host:port/path` are all accepted. A request must match every part, and the path matches on a segment boundary (`host/openai` matches `/openai` and `/openai/x`, not `/openaiz`). Plain-host entries behave exactly as before. See [Configuration](docs/configuration.md#custom-intercept-addresses).
+
+### Changed
+- Ruby 4.0 was added to the CI matrix ([#113](https://github.com/Coolhand-Labs/coolhand-ruby/pull/113)) and then removed again before release: its job could not `bundle install` against the locked dependencies (`BUNDLED WITH 2.3.6`, the conditional `pry-byebug`/`debug` Gemfile entry and `unicode-emoji 4.1.0`). CI covers Ruby 3.1–3.4 until the lock can support 4.0.
+
+### Fixed
+- `examples/anthropic_example.rb` could not run against the pinned `anthropic` 0.4.x gem: it relied on the client reading `ANTHROPIC_API_KEY` from the environment and on object-style response access, and it targeted a retired model. It now passes `access_token:` explicitly, reads the response as a Hash, and uses `claude-haiku-4-5-20251001`. Found by running it against a live key during release validation.
+
+### Security
+- **Azure OpenAI "On Your Data" datastore credentials are now redacted from captured request bodies** ([#115](https://github.com/Coolhand-Labs/coolhand-ruby/pull/115)) — a request's `data_sources`/`dataSources` entries can carry live credentials (Azure AI Search API keys, Cosmos/Mongo connection strings, Elasticsearch encoded keys) that header and URL sanitization never looked at. `BaseInterceptor.sanitize_body` now replaces any value under those entries whose key name contains `key`, `token`, `secret`, `password`, `credential`, `connectionstring` or `signature` (separators and case ignored) with `[REDACTED]` before the log is forwarded. Message content and tool definitions outside `data_sources` are untouched.
+- **Release-time hardening from a whole-package security review** ([#148](https://github.com/Coolhand-Labs/coolhand-ruby/pull/148), plus fixes made on the release branch):
+  - `Coolhand.log` no longer raises when stdout is unwritable. Previously a failing `puts` inside the interceptor's `ensure` block could replace the host application's own LLM response with an `IOError`.
+  - A bad `intercept_addresses`/`exclude_api_patterns` value (e.g. a String or Symbol instead of an array of Strings) now degrades to "don't capture" instead of raising into every intercepted request.
+  - `BaseInterceptor.sanitize_url` now fails closed on an unparseable URL, dropping userinfo, query and fragment rather than returning the raw URL with credentials intact.
+  - Header redaction now also matches names containing `auth`, `passw`, `credential`, `bearer`, `jwt` or `session` (e.g. `X-Auth`, `X-Session-Id`, `X-Jwt`). **Migration note:** headers such as `x-session-id` now appear as `[REDACTED]` in Coolhand.
+  - `sanitize_body` matches the `data_sources` key case- and separator-insensitively, and also redacts `pwd`, `passw*`, `bearer` and `jwt` credential keys.
+  - Hosts with a trailing dot (`api.openai.com.`) are now matched like their dotless form.
+  - `OpenAi::WebhookValidator` rejects a bare `whsec_` secret, which decodes to an empty HMAC key and would make signatures forgeable.
+
+### Documentation
+- Clarified that Google's "Gemini Enterprise Agent Platform" is the new marketing name for Vertex AI and does not change `aiplatform.googleapis.com` or `Coolhand::Vertex` ([#118](https://github.com/Coolhand-Labs/coolhand-ruby/pull/118)).
+
 ## [0.6.0] - 2026-09-12
 
 ### Added

data/README.md

@@ -103,6 +103,35 @@ Search is a parameter on the list endpoint, not a route of its own, and the `Unm
 
 For the full filter reference, pagination, and error handling, see [Reading Templates →](docs/template-search.md).
 
+### Cost and performance metrics
+
+Pass `include_metrics: true` to `search_templates` (or `search_workloads`) for the dashboard's cost and performance numbers, over a rolling `days_back` window or an explicit `since:` / `until:` one. `search_logs` carries each log's `cost` and can sort and filter by it.
+
+```ruby
+window = { since: Time.utc(2026, 9, 1), until: Time.utc(2026, 10, 1) }
+
+Coolhand.workload_service.search_workloads(include_metrics: true, **window).workloads
+  .map { |w| [w[:name], w[:metrics][:total_cost]] }
+
+Coolhand.log_service.search_logs(order: 'cost_desc', min_cost: 1.0, per: 10, **window).logs
+```
+
+See [Reading Workloads →](docs/workload-search.md) and [Reading Logs →](docs/log-search.md).
+
+## Linking Feedback to an Optimization
+
+Attach feedback to an optimization as evidence, one at a time or in bulk. These require your **private** API key and **raise** `Coolhand::Error` on failure (`Coolhand::HttpError` for non-2xx responses).
+
+```ruby
+links = Coolhand.optimization_feedback_link_service
+
+link = links.link_feedback('optimizationHashid', 'feedbackHashid', note: 'why')
+links.bulk_link_feedback('optimizationHashid', %w[fb1 fb2 fb3]) # => { linked:, already_linked:, errored:, not_found: }
+links.unlink_feedback('optimizationHashid', link[:id])
+```
+
+For batching, error semantics, and details, see [Linking Feedback →](docs/feedback-links.md).
+
 ## Rails Integration
 
 ### Configuration
@@ -120,8 +149,8 @@ Coolhand.configure do |config|
   config.silent = Rails.env.production?
 
   # Specify which LLM endpoints to intercept (array of strings)
-  # Optional - defaults to OpenAI, Anthropic, ElevenLabs, Google Gemini, and GitHub Models
-  # config.intercept_addresses = ["api.openai.com", "api.anthropic.com", "api.cohere.ai"]
+  # Optional - defaults to every provider listed under "Supported Libraries" below
+  # config.intercept_addresses = ["api.openai.com", "api.anthropic.com", "api.cohere.com/v2/chat"]
 end
 ```
 
@@ -178,10 +207,11 @@ 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 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_addresses` | Array | All [supported providers](#supported-libraries) (`DEFAULT_INTERCEPT_ADDRESSES`) | Array of API hosts to monitor (matched by host, optionally pinned to a port and/or path prefix). 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) |
+| `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) |
 
 ## Usage Examples
 
@@ -337,10 +367,18 @@ The monitor works with multiple transport layers and Ruby libraries:
 **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
+- Azure OpenAI Service, Azure AI Foundry, and Azure Machine Learning managed online endpoints (dedicated hosts, multi-service Azure AI Services hosts, and serverless/MaaS deployments) — see [Configuration](docs/configuration.md) for the full list of covered hosts
 - AWS Bedrock (OpenAI-compatible endpoint)
 - Cloudflare AI Gateway
 - OpenRouter
 - OpenCode Zen (`opencode.ai`)
+- DeepSeek (`api.deepseek.com`)
+- Mistral (`api.mistral.ai`)
+- Perplexity (`api.perplexity.ai`)
+- xAI (`api.x.ai`)
+- Cohere (chat and embed endpoints only, on `api.cohere.com` and `api.cohere.ai`)
+- TypeSafe Jev / System One (`api.typesafe.ai/v1/systemone`)
+- Ollama (self-hosted, default port 11434 — chat, generate and embed endpoints) — see [Configuration](docs/configuration.md) for non-default hosts
 
 **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.
 
@@ -426,13 +464,16 @@ 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)
+- 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)
 
 ## 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
+- **[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
 - **[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/docs/configuration.md

@@ -39,6 +39,25 @@ 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.
 
+## Asynchronous Logging
+
+By default Coolhand ships each captured request to its API from background worker threads (one for per-request logs, a separate one for batch jobs), so a slow or unreachable Coolhand backend never adds latency to your own LLM calls. The request-path work is limited to capturing and sanitizing the payload.
+
+```ruby
+Coolhand.configure do |config|
+  config.async_logging = false # default: true — send inline, in the intercepted call's request path
+end
+```
+
+**How it behaves:**
+- The queue is bounded at 1,000 pending logs. If Coolhand is down long enough to fill it, the *oldest* pending log is dropped (with a log line) rather than blocking your app or growing memory.
+- The bound is on the *number* of pending logs, not their size: each holds its captured response body in memory until sent, so a long Coolhand outage under heavy traffic with large responses can hold a lot of memory. Batch jobs use their own lane, so a long-running batch never delays or evicts per-request logs.
+- A forked process (Puma/Unicorn workers, Spring) starts its own worker automatically.
+- Pending logs are flushed at process exit (up to 5 seconds in total, so a batch job still running at exit may be only partly logged). In a short-lived script, or to wait explicitly, call `Coolhand.flush(timeout: 5)` — it returns `true` once everything has been sent.
+- OpenAI and Vertex batch results are processed as a single background job per batch.
+- `config.debug_mode` always runs inline so printed payloads appear in order.
+- Logs queued but not yet sent are lost if the process is killed hard (`kill -9`, OOM). Set `async_logging = false` if you need delivery before each call returns.
+
 ## 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:
@@ -74,7 +93,13 @@ Setting `intercept_addresses` **replaces** the default list entirely, so include
 
 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.
+Each entry is matched against the request's parsed host (optionally with a port and path prefix, see below) — 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 that merely mention a host can't trigger a false match.
+
+An entry can also pin a port (`host:port`) and/or a path (`host/path`, or `host:port/path`), and then a request must match all of them. Cohere, TypeSafe and Ollama are defaulted this way: `api.cohere.com/v2/chat`, `api.typesafe.ai/v1/systemone`, and `*:11434/api/chat` (plus `/api/generate`, `/api/embed`, `/api/embeddings`, also for `127.0.0.1`). Ollama has no fixed host, so its defaults require Ollama's default port *and* an Ollama path — an app's own unrelated `/api/chat` on another host or port is not captured. To capture an Ollama server on a dotted host or IP, or a non-default port, add entries such as `192.168.1.5:11434/api/chat` or `ollama.internal:8080/api/chat`. An IPv6 loopback server (`[::1]:11434`) is already covered by the defaults.
+
+Path-anchoring is also how the Azure defaults work: multi-service hosts like `cognitiveservices.azure.com/openai/` (Azure AI Services, where Speech, Vision, Language and Content Safety share a domain with LLM inference) only match paths under the given prefix, after the host itself has matched.
+
+**Note on Azure ML managed online endpoints:** `inference.ml.azure.com` and `inference.ml.azure.us` are intentionally captured *without* a path anchor. Every Azure ML managed online endpoint scores at `/score` regardless of what model sits behind it, so there's no path that distinguishes an LLM deployment from a tabular or vision one — this gem chooses to capture broadly rather than silently miss LLM deployments. If that over-captures for your setup, override `intercept_addresses` to a custom list omitting these two entries.
 
 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.
 
@@ -82,7 +107,7 @@ A small number of Google API endpoints use a colon-suffixed path (e.g. `.../gemi
 
 ## 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.
+`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 a small built-in list (see `Coolhand::Configuration::DEFAULT_EXCLUDE_API_PATTERNS`) that suppresses Vertex AI batch job management noise (`/batchPredictionJobs/`) and Azure OpenAI control-plane paths (file, batch, and fine-tuning management under `/openai/` and `/openai/v1/`) that aren't inference traffic.
 
 ```ruby
 Coolhand.configure do |config|

data/docs/feedback-links.md

@@ -0,0 +1,48 @@
+# Linking feedback to an optimization
+
+Attach feedback to an optimization as supporting evidence. `Coolhand::OptimizationFeedbackLinkService`
+wraps `POST /api/v2/optimizations/{optimization_id}/feedback_links` (single and bulk share the route,
+chosen by the body) and `DELETE /api/v2/optimizations/{optimization_id}/feedback_links/{id}`.
+
+These methods require your **private** API key; the public key gets a `401`.
+
+```ruby
+require "coolhand"
+
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_PRIVATE_API_KEY")
+end
+
+links = Coolhand.optimization_feedback_link_service
+
+# One feedback. link[:id] is the link's hashid, not the feedback's.
+link = links.link_feedback("optimizationHashid", "feedbackHashid", note: "why")
+
+# Many feedbacks.
+result = links.bulk_link_feedback("optimizationHashid", %w[fb1 fb2 fb3])
+result # => { linked: 2, already_linked: 1, errored: 0, not_found: [] }
+
+# Remove a link.
+links.unlink_feedback("optimizationHashid", link[:id])
+```
+
+## Bulk behavior
+
+- The server accepts at most 100 ids per request. `bulk_link_feedback` splits longer lists into
+  batches of 100, sums `linked` / `already_linked` / `errored` and concatenates `not_found`.
+- Already-linked ids count as `already_linked`, not errors. Unknown, malformed and other-client ids
+  are all reported in `not_found`.
+- If a batch fails, the call raises and earlier batches stay applied. Repeating the call is safe.
+- `link_feedback` is not retry-safe: after a transport error, a `422` "already linked" on retry may mean
+  the first attempt succeeded. Use `bulk_link_feedback` with a single id for retry-safe semantics.
+- An empty list or a blank id raises `Coolhand::Error` before any request is made.
+- Ids are trimmed of surrounding whitespace but not de-duplicated client-side.
+
+## Errors
+
+Unlike the logging writes, all three methods raise. A non-2xx response raises `Coolhand::HttpError`
+whose `status` is the HTTP code: `401` missing or public key, `404` unknown optimization, feedback or
+link, `422` invalid input, an already-linked feedback (single mode) or a `note` that is too long.
+Client-side validation and transport failures raise `Coolhand::Error`.
+
+`config.debug_mode` does not suppress these calls: they change server state, so they are always sent.

data/docs/log-search.md

@@ -0,0 +1,102 @@
+# Reading Logs (Search + Get)
+
+`Coolhand::LogService` reads logs back out of Coolhand, with the per-log `cost` the dashboard shows.
+The write side, `Coolhand.logger_service`, is a different class. It wraps two read-only endpoints:
+
+| method | endpoint |
+|---|---|
+| `search_logs` | `GET /api/v2/llm_request_logs` |
+| `get_log` | `GET /api/v2/llm_request_logs/{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
+
+logs = Coolhand.log_service
+
+# The ten most expensive logs of the last 30 days
+result = logs.search_logs(since: Time.now.utc - (30 * 86_400), order: "cost_desc", per: 10)
+result.logs.each { |log| puts "#{log[:id]} #{log[:model]} $#{log[:cost]}" }
+
+detail = logs.get_log(result.logs.first[:id])
+detail[:cost_breakdown][:input_cost]
+```
+
+## `search_logs`
+
+All keywords are optional, and named after the wire parameters (`sort` maps to `q[s]`). Two wire
+parameters are not exposed: the `q[source_api_in][]` array filter, so use the single-value `source_api`
+keyword, and the `per_page` alias, since this gem only sends `per`.
+
+| keyword | type | notes |
+|---|---|---|
+| `template_id`, `workload_id` | String | Hashids. One that does not decode, or that belongs to another client, is a `422`. |
+| `system_prompt_contains`, `user_prompt_contains` | String | Case-insensitive substring. |
+| `model`, `source_api`, `source_api_result`, `source_application` | String | Exact match. `source_api_result` is `success`, `failed`, `operational` or `unmatched`. |
+| `project_path` | String | Exact match against `metadata.project_path`. |
+| `unmatched_only` | Boolean | Only logs with no template. |
+| `days_back` | Integer | Last N days. Unset means unrestricted. Ignored when `since` is given; with only `until`, the window is `days_back` long ending at `until`. |
+| `since`, `until` | Time, DateTime, Date or String | Bounds on `created_at`: `since` inclusive, `until` exclusive. See [Windows](workload-search.md#windows-since-and-until). |
+| `min_cost` | Numeric | Only logs whose `cost` (USD) is at least this. `0` is sent. |
+| `order` | String | `"cost_desc"` sorts by `cost`, highest first, replacing `sort`. Any other value is a `422` from the server. |
+| `include_prompts` | Boolean | Adds `:system_prompt` and `:user_prompt`, each truncated to 500 characters. |
+| `include_total` | Boolean | Asks the server for the `X-Total-*` headers. Off by default there (it skips a `COUNT(*)`). |
+| `sort` | String | Ransack sort expression, sent as `q[s]`, e.g. `"created_at desc"`. |
+| `page`, `per` | Integer | 1-based; `per` defaults to 25, max 100. |
+
+`min_cost` and `order: "cost_desc"` only consider logs that can be priced (non-nil `cost`). The cost is
+computed per log, so on a client with a lot of history combine them with `since` or `days_back`, or the
+query can time out (`504`).
+
+### Return value
+
+A `Coolhand::LogSearchResult`, a `Struct` with `#logs` and `#pagination`. The response body is a bare
+array, never wrapped. Rows are Symbol-keyed Hashes: `:id`, `:collector`, `:source_api`,
+`:source_application`, `:metadata`, `:source_api_result`, `:model`, `:template_id`, `:template_name`,
+`:input_tokens`, `:output_tokens`, `:latency_ms`, `:created_at`, `:updated_at`, `:ingest_evidence` and
+`:cost`.
+
+`:cost` is a Float in USD, or `nil` when the log has no tokens or its model has no pricing.
+
+**Pagination without totals.** `X-Page` and `X-Per-Page` are always sent, but `X-Total-Count` and
+`X-Total-Pages` only come with `include_total: true`. Without it, `pagination.total_count` and
+`total_pages` are lower bounds the gem derives, not counts, and `has_next_page` is true when the page
+came back full. Pass `include_total: true` when you need real totals.
+
+## `get_log(id, section: nil, max_chars: nil, search_query: nil, include_thinking: nil)`
+
+`id` is the log hashid. Returns the full log as a Symbol-keyed Hash: the list fields plus the prompts and
+`:output`, and:
+
+| field | type |
+|---|---|
+| `:url` | String: the log's dashboard path (`/c/<client>/llm_request_logs/<id>`) |
+| `:cost` | Float or nil |
+| `:cost_breakdown` | Hash or nil: `:total_cost`, `:input_cost`, `:output_cost`, `:cached_input_cost`, `:cache_creation_input_cost`, `:reasoning_output_cost` |
+
+`section` (`"full"`, `"beginning"`, `"end"`), `max_chars` and `search_query` bound or search the content;
+`include_thinking` adds `:thinking_response`. Truncation and search are reported back as `:truncated`,
+`:total_chars`, `:search_query` and `:matches`. Only directly-collected logs are fetchable; internally
+generated records are a `404`.
+
+## Errors
+
+The read methods raise where the write methods log and return `nil`. `Coolhand::HttpError` carries
+`#status` and `#body`.
+
+| status | when |
+|---|---|
+| `401` | No API key, an invalid key, or the public key. |
+| `404` | `get_log` only: unknown id, another client's log, or an internally generated record. |
+| `422` | Bad `template_id`, `workload_id`, `days_back`, `since`, `until`, `min_cost`, `order` or `max_chars`. |
+| `504` | The search exceeded the statement timeout. Narrow the window and retry. |
+
+`Coolhand::Error` covers no API key configured, a transport failure, a body that is not valid JSON, a
+non-array list body, and a blank `id` passed to `get_log`. An unsupported `since`/`until` type raises
+`ArgumentError` before any request.

data/docs/openai.md

@@ -14,7 +14,7 @@ Requires Rails — `Coolhand::WebhookInterceptor` and `Coolhand::OpenAi::BatchRe
 - 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.
+`intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` — that part requires no code in your controller action. The batch's status is checked inline in the `before_action`, but for a completed batch the two JSONL file downloads and the one-request-log-per-item sends run on Coolhand's [background log thread](configuration.md#asynchronous-logging), so a large batch doesn't hold up your webhook response. (With `config.async_logging = false` this all runs inline, and a large batch can trip your webhook endpoint's timeout and OpenAI's retry behavior.) 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
 

data/docs/template-search.md

@@ -41,7 +41,7 @@ This is **not** a port of the `search_templates` MCP tool, and the two do not ag
 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_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil, include_system: nil, include_metrics: nil, days_back: nil, since: nil, until: 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.
@@ -56,6 +56,10 @@ and this API's already agree, so there is no second spelling to translate throug
 | `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. |
+| `include_metrics` | Boolean | Adds a `:metrics` Hash to every row. See [Metrics](#metrics). |
+| `days_back` | Integer | Rolling metrics window in days (server default 28, max 365). Ignored unless metrics are requested, and when `since` is given. |
+| `since` | Time, DateTime, Date or String | Metrics window start, inclusive. Overrides `days_back`. |
+| `until` | Time, DateTime, Date or String | Metrics window end, exclusive. Defaults to now. |
 | `page` | Integer | 1-based. |
 | `per` | Integer | Default 25, max 100, both enforced server-side. |
 
@@ -138,11 +142,14 @@ unmatched = Coolhand.template_service
 puts unmatched[:log_count]
 ```
 
-## `get_template(id)`
+## `get_template(id, include_metrics: nil, days_back: nil, since: nil, until: nil)`
 
 `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:
+Returns a Hash with every list field above, **plus** the full untruncated regexes the list omits, and
+a `:metrics` Hash. Unlike the list, metrics are **on by default** here: pass `include_metrics: false` to
+omit them, which also skips the window validation. `days_back`, `since` and `until` set the window
+exactly as they do on the list, and an invalid one is a `422` unless metrics are off.
 
 | field | type |
 |---|---|
@@ -153,6 +160,41 @@ Unlike the list, this filters on nothing but client ownership: a deprecated or s
 reachable by id with **no opt-in flag**, because inspecting one of those is the usual reason to
 fetch a template directly.
 
+## Metrics
+
+With `include_metrics: true` every row (and by default the `get_template` result) carries `:metrics`,
+computed by the same SQL as the dashboard, so tiered pricing, cached-token discounts and reasoning tokens
+are applied. `Coolhand.workload_service` returns the same object per workload, rolled up across its
+templates ([Reading Workloads](workload-search.md)).
+
+Averages and counters cover non-failed, directly-collected client logs inside the window. Keys are the
+wire names, as Symbols.
+
+| field | type | notes |
+|---|---|---|
+| `:days_back` | Integer or nil | `nil` when `since` defined the window. |
+| `:since`, `:until` | String | The resolved window, ISO-8601 UTC. |
+| `:request_count` | Integer | |
+| `:failure_count` | Integer | Failed logs. |
+| `:error_rate` | Float or nil | `nil` when `failure_count` is 0. |
+| `:error_rate_change` | Float or nil | Against the window of the same length immediately before. |
+| `:avg_cost_per_request` | Float or nil | `nil` when no log in the window could be priced. |
+| `:total_cost` | Float or nil | |
+| `:priced_request_count` | Integer | The logs `total_cost` covers: non-failed, with tokens, model has pricing. |
+| `:long_context_request_count` | Integer | Priced logs that crossed their model's input-token pricing tier. |
+| `:total_input_tokens`, `:total_output_tokens` | Integer | Raw token columns summed over non-failed logs, not cache-adjusted. |
+| `:avg_input_tokens`, `:avg_output_tokens` | Integer or nil | |
+| `:avg_latency_ms` | Float or nil | |
+| `:correctness_score`, `:sentiment_score`, `:revision_score` | Float or nil | `sentiment_score` and `revision_score` are all-time, not windowed. |
+| `:first_request_at`, `:last_request_at` | String or nil | Lifetime, not windowed. |
+
+Summing the per-log `cost` from [Reading Logs](log-search.md) can exceed `total_cost`, because the log
+`cost` is also computed for failed logs and logs with a zero token count.
+
+Windows follow the rules in [Reading Workloads](workload-search.md#windows-since-and-until). A window
+error is a `422` on the `since` or `until` key. Metrics add aggregate statements, so expect a slower
+response, and a `504` on a large page.
+
 ## Errors
 
 The write methods in this gem (`create_feedback`, `create_log`, `send_llm_request_log`) log a
@@ -186,7 +228,7 @@ end
 |---|---|
 | `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. |
+| `422` | Unrecognised `status`, a `workload_id` that does not decode or belongs to another client, or a bad `days_back`, `since` or `until` when metrics are requested. |
 | `504` | See below. |
 
 ### `504` is expected, and retryable

data/docs/vertex.md

@@ -6,6 +6,8 @@ For monitoring regular (non-batch) Vertex AI calls, no extra setup is required b
 
 Requires Rails — `Coolhand::Vertex::BatchResultProcessor` logs via `Rails.logger` internally. `config.capture = false` and `Coolhand.without_capture` do not suppress these logs: unlike the passive Net::HTTP interceptor, calling this processor is an explicit, deliberate act, so it always sends.
 
+> **Note:** As of May 2026, Google markets this product as "Gemini Enterprise Agent Platform" rather than "Vertex AI." The API endpoint (`aiplatform.googleapis.com`) and Ruby SDK are unchanged — it's a console/marketing rename, not an SDK rename — so `Coolhand::Vertex` naming stays accurate here. It's also still a distinct integration from the separate Gemini Developer API (`generativelanguage.googleapis.com`), which Coolhand intercepts independently.
+
 ## Usage
 
 ```ruby
@@ -13,6 +15,7 @@ require "coolhand/vertex/batch_result_processor"
 ```
 
 - Call the `Coolhand::Vertex::BatchResultProcessor` service with `batch_info` and the downloaded batch results.
+- For a succeeded job, the per-item request logs are sent from Coolhand's [background log thread](configuration.md#asynchronous-logging) as a single job, so `call` returns without waiting on the Coolhand API (set `config.async_logging = false` to send inline).
 - Optionally pass `model:` to populate the logged `model` field. It falls back to a `"model"` key in `batch_info` if present, and is omitted from the payload entirely when neither is available. If the value (from either source) looks like a Vertex model resource path (`publishers/<publisher>/models/<id>` or `projects/<project>/locations/<location>/models/<id>`), it's normalized down to just the trailing id/version before being logged; any other string is sent as-is.
 - `batch_info["name"]` must be the exact Vertex job resource name (`projects/<project>/locations/<location>/batchPredictionJobs/<job-id>`), and `batch_info["startTime"]`/`["endTime"]` must be valid ISO 8601 timestamps — a batch with a missing or malformed resource name or timestamps is skipped entirely (logged as an error) rather than sent with a broken URL.
 - If `endTime` precedes `startTime` (e.g. clock skew), the batch is still logged — `duration_ms` is clamped to `0` and a warning is logged — rather than dropping the results.