@combycode/llm-sdk 2.3.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,435 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [3.1.0] — 2026-08-25
+
+### Added
+
+- **A provider can declare a hosted tool it will not run beside certain content** (`toolConstraints`
+  in a wire spec, plus a `hasPartType` condition). Measured 2026-08-25: Google answers 400 `The mime
+  type: video/mp4 is not supported for code execution` when `code_interpreter` accompanies a PDF or a
+  video. Images are fine, `web_search` is fine, and OpenAI accepts every combination — so it is one
+  provider's rule, and it lives in that provider's spec as data rather than as an `if` in the builder.
+
+  A matched constraint drops the tool — `hasTool` reports it absent, so the spec's existing guard
+  omits it with no further edit — and records why on the built request. `LLMClient` emits each as
+  `onWarning` with code `request_adjusted`, on both `complete()` and `stream()`. Dropping it quietly
+  would trade a confusing error for the silent loss of a capability the caller asked for.
+
+- **Any spelling of a model id finds the model, and every helper resolves it the same way.**
+  Providers spell one version several ways and users copy whichever they saw: `gpt-4.1` / `gpt-4-1`,
+  `gemini-2.5-flash` / `gemini-2-5-flash`, `claude-haiku-4.5` / `claude-haiku-4-5`. Only some are
+  callable, and the rest missed the catalog outright — no price, no capabilities — and were then
+  forwarded to the provider verbatim, turning a spelling difference into a 404.
+
+  Catalog lookups are now insensitive to the separator between two digits and to case, so ~556
+  previously-unresolvable spellings reach their entry. The rule is deliberately narrow — only a
+  separator between two DIGITS moves — and is verified across the shipped catalogs to merge nothing:
+  1016 normalized keys, zero collisions.
+
+  `resolveModelId()` now always returns something callable. A spelling the provider itself accepts is
+  sent unchanged; one it would reject is corrected to the canonical id instead of being forwarded;
+  an unknown id still passes through verbatim, so fine-tunes and same-day releases keep working.
+
+### Fixed
+
+- **`createRealtime()` never translated the model id.** It parsed the provider but skipped the
+  catalog step every other helper performs, so a realtime session was the one path that sent our
+  slug instead of the provider's id. All helpers now share the single resolution step, and a test
+  calls each one and reads the wire so a helper that forgets fails CI rather than a user's request.
+
+- **An Anthropic model is reachable by the name Anthropic documents.** `claude-haiku-4-5` — the
+  spelling in Anthropic's own docs, and one the API accepts — matched no catalog key and no alias,
+  because `/v1/models` lists only the dated snapshot (`claude-haiku-4-5-20251001`) while our slug
+  dots the version (`claude-haiku-4.5`). `get()` and `getPricing()` missed in silence, and an
+  unpriced model is indistinguishable from a free one: reported from production as 72k tokens
+  billed at $0.00.
+
+  The undated form is now carried as an alias for the four affected entries (`claude-haiku-4-5`,
+  `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-opus-4-1`), derived in the catalog pipeline so a
+  regeneration keeps it. Anthropic-only, and deliberately so — the same date-stripping applied to
+  other providers invents ids that do not exist (`imagen-4.0-generate`, `command-r7b-12`), since
+  only there is the undated form a truncation rather than a real alias. Each was probed live.
+
+  `providerModelName` is untouched, so **what goes on the wire is unchanged**: a slug still
+  translates to its pinned snapshot, and an alias is still sent verbatim as the floating id the
+  caller chose. This widens what the catalog recognises, never what it calls.
+
+## [3.0.0] — 2026-08-24
+
+### Added
+
+- **Exact token counting for xAI**, via `/v1/tokenize-text`. Their own SDK reaches the tokenizer over
+  gRPC (`xai_api.Tokenize/TokenizeText`), which made it look like exact counts on xAI would cost a
+  protobuf dependency and an optional peer. Asking the REST host instead: it answers 200 with the
+  same token list, so this is one more spec-built request and the library stays zero-dependency.
+
+  All seven xAI text models now declare `count_api` — measured per model rather than generalised
+  from one success: the five image and video models do not answer the endpoint and stay on the
+  heuristic. On a short Cyrillic line the estimate and the tokenizer differ by 30% on emoji and 23%
+  on code.
+
+  One distinction the guide now spells out: Anthropic and Google count the message array a
+  completion would send, so their answer is what the completion is billed for, while xAI tokenizes
+  a STRING — exact for that text, excluding the chat framing around it.
+
+- **`createEngine({ checkResponseShapes: true })` — warn when a provider's response stops looking
+  like the one we learned to read.** A bad request returns 400 and you know at once; a bad response
+  returns 200, the parse succeeds, and the field we read is simply gone — for `usage.output_tokens`
+  that is cost reporting silently going to zero.
+
+  Four findings, on the warning bus as `response_shape_*`: a field never seen, a field that was
+  present in every recording and is now absent (what a rename looks like from outside), a
+  discriminator carrying a value nothing branches on (a new content-block type is dropped in
+  silence), and a streaming event type the parser does not handle. Off by default, never changes
+  what is parsed, and each distinct finding is reported **once per client** — a warning that repeats
+  every request is one people switch off.
+
+  The shapes are DERIVED from the recorded response corpus by `bun run derive:shapes`, never
+  hand-written, and a test re-checks every recorded body against them so the description cannot
+  drift from the recordings. Stream shapes are keyed per SSE event type: pooling them was the first
+  attempt and it cost the missing-field check entirely, since `message_start` and
+  `content_block_delta` share almost no fields.
+
+  The value of deriving rather than writing showed up immediately — a hand-written "normal
+  Anthropic response" in the first draft of the test was missing eight fields Anthropic sends on
+  every call (`stop_details`, `usage.service_tier`, `usage.cache_read_input_tokens` among them).
+  The check was right and the hand-written body was wrong.
+
+- **A recorded corpus of what providers send BACK** (`tests/fixtures/response-golden.json`, 42 cells).
+  All seven existing corpora describe REQUESTS; the parse side was exercised only against literals
+  written by hand in the test files, which tests what the author believed a provider returns. This
+  records the real thing — the pre-parse body, or the ordered SSE events — for seven adapters across
+  six shapes (text, tool call, parallel tool calls, structured output, streaming text, streaming
+  tool call), and replays them through the same `parseResponse` / `createStreamParser` with no
+  network.
+
+  `raw` is the provider's truth and moves only when `bun run record:responses --refresh` is run;
+  `parsed` is our behaviour and is recomputed on every test run, so a parser change surfaces as a
+  failure instead of as a quiet difference in what consumers receive. Two invariants are checked
+  across all providers at once: every non-streaming response yields usage and a finish reason, and
+  every stream ends in a terminal event.
+
+  The corpus was proven to fail on a renamed provider field, on a parser that drops the finish
+  reason, and on a cell quietly disappearing. It found both fixes below in its first run.
+
+- **The SDK's event stream is one discriminated union** (`HookEvent`). `HookMap` types a
+  subscription — `on('onCompletion', h)` has always known its own context — but the STREAM was
+  `(name, ctx: unknown)`, which pushed the type back onto the subscriber. `HookEvent` gives it one
+  variant per hook, derived from `HookMap` so the 51 cannot drift from the 51:
+
+  ```ts
+  hooks.onAny((e) => {
+    if (e.type === 'onCompletion') e.ctx.response?.usage;   // narrowed, no cast
+  });
+  ```
+
+  This is the shape the Python and Rust ports share: a tagged union and an `enum` over the same
+  catalog. A stream typed `ctx: unknown` has no equivalent in either — the consumer's only move is
+  to cast, which is exactly what the SDK's own telemetry adapter did.
+
+- **A model ships as callable only if it has been called.** The catalog-loader's probe was
+  advisory; 366 of 440 names had never been verified. Now `active: true` requires either a real
+  request that answered (`verifiedBy: 'probe'`) or the provider's own model list naming it
+  (`verifiedBy: 'listed'`, the only evidence available for an image or TTS model). Everything else
+  ships `active: false` — present, priced, but not offered to `selectModel`.
+
+  A name is called ONCE: later runs check the listing instead, which is free. A verified name that
+  disappears from the list is marked deprecated rather than re-probed. Verification went from
+  74/440 to 395/470.
+
+- **`scripts/pin-catalog.ts` and `freeze-wire-golden.ts --add-new`** — a catalog import brings
+  models with no wire-spec pin and no entry in the frozen request corpus, and the library asserts
+  both. Deriving the pin and appending only the unseen models keeps those invariants true without
+  re-freezing a baseline that exists to be stable.
+
+- **The last four hand-built surfaces are spec-driven**: exact token counting, live model listing,
+  file-content retrieval and the provenance check. With those, **every request the library sends
+  comes from a spec** — 145 of them. Nothing in `src/` assembles a URL, a header set or a body by
+  hand any more.
+
+- **MCP is spec-driven too, transport and OAuth.** The Streamable-HTTP transport's five requests
+  (call, notification, long-lived subscription, event stream, session delete) and the OAuth flow's
+  five (two discovery probes, dynamic client registration, code exchange, refresh) now come from 13
+  specs — as does the authorization URL the user's browser opens.
+
+  This is the point where the spec format stops being about LLM providers. A JSON-RPC envelope,
+  era-dependent routing headers, a form-urlencoded token grant and an SSE stream are all described
+  with the constructs a chat request already used.
+
+  Verified against two frozen corpora (23 transport artifacts, 11 OAuth), both shown to fail on
+  deliberate corruption, plus live runs of the MCP protocol example and the five-provider MCP tool
+  scenario. The OAuth half has no live coverage anywhere — that needs a real authorization server
+  and a browser — so its frozen bytes are the only oracle it has, which the wire README now says
+  out loud.
+
+- **Three more spec constructs**, each added because a real request needed it: `bodyKind: 'form'`
+  (the spec carries the FIELDS, the runtime encodes them — the same split multipart already used),
+  a header entry with `spread` (merge an evaluated object of headers, so a caller's header map and
+  a resolved bearer keep their precedence), and `queryEncoding: 'form'` (a space as `+` rather than
+  `%20`, which is what RFC 6749 prescribes for an authorization request and what the library
+  already sent).
+
+- `NormalizedRequest.wireSpec` — the catalog's pin, resolved by `LLMClient` and read by
+  the adapter. Absent for an uncatalogued model or an engine with no catalog, in which
+  case the adapter derives the spec the way it always derived the shape.
+
+- **`envelope.query` in the wire spec** — query parameters as data, each able to drop out on its
+  own. Splicing them into a `$join` URL only works while every parameter is present, and it left
+  the encoding to each caller: the hand-written backends disagreed about `encodeURIComponent`, so a
+  page token containing `+` paged from the wrong place and the API answered 200.
+
+- **`$each` in array templates** — the array analogue of `$spread`, for a `$map` that has to sit
+  beside literal entries. Google's `tools` array is exactly that shape.
+
+- **`scripts/gen-wire-registry.ts` (`bun run gen:registry`)** — regenerates the spec index from the
+  files on disk, with `--check` for CI. Specs have landed without their registry entry three times
+  now, and it fails silently: the spec becomes invisible to `WIRE_SPECS`, so the chain tests skip it
+  and the coverage audit reports it as neither referenced nor executed.
+
+- **A live hosted-retrieval example** (`31-hosted-retrieval`), run on OpenAI and Google by the
+  quality gate. Hosted retrieval had unit tests and documentation but had never once been executed
+  against a provider, which is how both defects below survived.
+
+### Changed
+
+- **`HookBus.onAny` receives one event object instead of `(name, ctx)`** (BREAKING). Handlers take
+  `(event: HookEvent)`; `event.type` narrows `event.ctx`.
+
+  ```ts
+  hooks.onAny((name, ctx) => { ... });   // before
+  hooks.onAny((event) => { ... });       // after
+  ```
+
+  The SDK's telemetry adapter was the only consumer, and it shows why the old shape was worth
+  breaking: it opened with `const c = ctx as Record<string, unknown>` and then cast per field —
+  `(c.response as { usage?: … })?.usage`, `c.latencyMs as number`, `(c.error as Error)?.message`.
+  Rename a context field and every one of those keeps compiling and quietly reads `undefined`,
+  which for the token and cost fields is a metric that silently goes to zero. All 26 casts in that
+  method are gone (0 left); the switch narrows instead, and the compiler now checks each field against the
+  context it actually belongs to.
+
+  Nothing is allocated when no catch-all is subscribed, so the per-chunk hot path is unchanged.
+- **The catalog is current again, and the chain that maintains it works end to end.** The
+  catalog-loader's export pointed at the catalogs' old home, which was BOTH its write target and
+  its merge base — so the "never drop a shipped model, never blank a price" guarantee silently
+  guaranteed nothing, and a run would have dropped 10 models and all 284 `wireSpec` pins. Repointed,
+  and it now refuses to run at all if the merge base is missing.
+
+  With it fixed, a full run brought the catalog up to date: +99 models discovered, 57 prices
+  changed (all four provider pricing pages had moved), 42 tokenizer strategies delivered, 61 models
+  marked `active: false`, and 48 given a deprecation date the sources announced. The `wire` field
+  removed in 3.0.0 was still riding along on 26 entries and is now dropped.
+
+- **The catalog is loaded by default** (BREAKING, behaviour). `createEngine()` and `LLMClient` used
+  to start with an EMPTY catalog unless the caller passed `catalog: 'defaults'`. Three things fell
+  back silently as a result: the wire spec was derived from the model id instead of read from its
+  pin, every price was unknown, and every token count was the 4-chars-per-token estimate. Each is
+  the right answer for a model this build has never heard of, which is why nothing looked wrong.
+
+  This is the prerequisite the 3.0.0 design named (report 037, R1): the adapters can only be driven
+  by per-model data if that data is actually there. The bundled catalogs are statically imported
+  either way, so leaving them unloaded never saved a byte — it cost about a millisecond of indexing
+  per engine and bought silence.
+
+  Opting out is now the explicit act: `catalog: false` or `catalog: 'empty'`.
+
+- **`AnthropicCountApi` and `GoogleCountApi` take an `EngineFetch`, and it is required** (BREAKING).
+  They defaulted to `globalThis.fetch`, so every exact token count for Anthropic and Google went out
+  AROUND the NetworkEngine: no queue, no rate limiting, no retry, no telemetry span — while every
+  other file in the library states that all HTTP goes through the injected fetch. `countTokens()`
+  passes `engine.fetch` for you, so the documented path needs no change; a `HybridTokenCounter`
+  built with `countApiKeys` but no `fetch` now says so and falls back to the heuristic instead of
+  silently leaving the engine.
+
+  The default is gone rather than replaced, because a default that silently bypasses the engine is
+  what produced this.
+
+- **MCP header assembly is one ordered list instead of three helpers.** Which headers a call
+  carries — session, protocol version, the modern `Mcp-Method` / `Mcp-Name` routing pair — was
+  decided by three private methods and by the order their results were spread into an object
+  literal. It is now a declared sequence, and the two rules that genuinely are not data (era
+  detection, and reading a subject from a different param per method) are named registry entries
+  the coverage audit executes.
+
+  One asymmetry was preserved rather than tidied: a NOTIFICATION carries no routing headers, which
+  is what the transport has always sent. The freeze caught the attempt to "fix" it, and there is no
+  modern server here to test the change against.
+
+- **The chat adapters build their requests from the wire specs.** All five —
+  `anthropic/messages`, `google/generateContent`, `google/interactions`,
+  `openai/responses` and `openai/chat-completions`, the last two also covering the xAI
+  and OpenRouter flavors — now interpret the spec the catalog pins the model to, instead
+  of assembling the body by hand. 806 lines of request-building code became 147.
+
+  The three OpenAI-compatible subclasses are the clearest case: xAI and OpenRouter each
+  overrode `buildRequest` to call `super`, then rename `max_tokens`, strip `reasoning`,
+  remap the service tier and merge routing options. Every one of those edits is already
+  the flavor overlay in the shared spec, so naming the flavor is now the entire override.
+
+  **The wire did not move.** A corpus frozen from 2.3.0 — 290 subjects x 22 request
+  shapes, both the pinned and the id-derived route — is compared on every CI run, and all
+  12,760 comparisons are byte-identical to what 2.3.0 sent. Verified live against all five
+  providers as well; the specs are proven, not assumed.
+
+  Two supporting moves: `wire-transforms` left `src/wire/` (it imports from `src/llm`, and
+  the new edge would otherwise have made a cycle), and the runtime loads a chat-only spec
+  set rather than the full 71-spec index, so nothing is bundled that nothing executes.
+  Cost: +15 KB packed, and ~5 microseconds per request against a network call.
+
+- **Model-band selection is data, not code.** Which chain node an UNPINNED model uses now comes
+  from `src/wire/pins/*.json` — ordered regex rules plus a default — instead of version arithmetic
+  written in TypeScript. The Python and Rust ports read the same file rather than each
+  re-implementing the rule and drifting from it, which is how 2.2.1 happened.
+
+  The fallback itself is unchanged and still matters: it is how the SDK behaves for a model
+  released after this build, and for any engine run without a catalog. Verified against every id
+  the previous code handled, plus dated snapshots, legacy family-last ids, and plausible future
+  releases.
+
+  One deliberate fix came out of it: the old pair of helpers disagreed on case — one lower-cased
+  the model id and the other did not — so `CLAUDE-OPUS-4-6` lost a `top_k` that model accepts. The
+  pin table lower-cases consistently.
+
+- **The hosted retrieval backends build their requests from wire specs.** OpenAI vector stores,
+  Google file search stores and xAI Grok collections — 23 hand-assembled requests across three
+  files — now come from 24 specs. This was the largest remaining block of request construction
+  written three times over, once per provider.
+
+  xAI shows why it matters: collections span two hosts with two separate credentials, and which
+  pair a call used was decided by whichever bearer helper the author typed next to the URL. It is
+  now a property of the endpoint, declared in the spec.
+
+  Verified against a corpus frozen from the pre-migration commit — 41 requests, byte-identical —
+  and by a live end-to-end run on both providers.
+
+### Fixed
+
+- **An explicit `provider` was ignored whenever the model id contained a slash — sending the API key
+  to the wrong company.** `resolveModel` read the model's `vendor/` prefix first and fell back to the
+  explicit argument only for a bare id. Every OpenRouter model id is `vendor/model`, so the most
+  ordinary OpenRouter call there is —
+
+  ```ts
+  createLLM({ provider: 'openrouter', model: 'openai/gpt-5.4-nano', apiKey })
+  ```
+
+  — resolved to the provider `openai` and sent the **OpenRouter key to api.openai.com**, which
+  answered `Incorrect API key provided: sk-or-v1…`. A vendor outside our five failed differently and
+  no better: the prefix was cast to a `ProviderName`, so `qwen/qwen3` produced a provider literally
+  named `qwen` and died later as "no default adapter for provider 'qwen'".
+
+  An explicit provider now wins, and a redundant leading `<provider>/` is stripped, so the catalog's
+  own `openrouter/openai/gpt-5.4-nano` slug resolves to the OpenRouter model `openai/gpt-5.4-nano`.
+  Prefix parsing without a provider is unchanged and stays permissive — `estimate()` prices models
+  catalogued under providers nobody can call. Affects all nine call sites: `createLLM`, `batch`,
+  `embed`, `moderate`, `transcribe`, `createRealtime`, `countTokens`, `estimate`, `estimator`.
+
+- **Google's `responseId` was thrown away and replaced with a random UUID.** `parseResponse` minted
+  `crypto.randomUUID()` under a comment claiming generateContent returns no id — it returns
+  `responseId` at the top level, and every recorded response carries one. Two consequences: the parse
+  was not deterministic, so the same bytes produced a different `response.id` each time and nothing
+  keyed on it could correlate; and a cache hit, which replays the stored body, reported a different
+  id than the call that populated it. The provider's id is now used, with the generated one kept as
+  a fallback for older payloads.
+
+- **`batch`, `embed`, `transcribe` and `moderate` sent our SLUG instead of the provider's id.**
+  Only `createLLM` translated through the catalog, so those four worked purely for models whose
+  canonical id happens to be the callable one. The moment the sample corpus moved to
+  `claude-haiku-4.5`, every batch request came back `not_found_error: model: claude-haiku-4.5` —
+  two requests, zero successes, and an exit code of 0 to go with it.
+
+  All four now send `providerModelName` while keeping the slug for pricing and catalog lookups,
+  which are keyed by it. A test asserts the distinction and was checked against the unfixed code.
+
+- **Exact token counting works, for the first time.** `HybridTokenCounter` picks its strategy from
+  the catalog's `tokenizer.strategy`, and no shipped model declared one — so every count fell back
+  to the 4-chars-per-token estimate and neither exact path had ever run. All 455 models now carry a
+  strategy: `count_api` for Anthropic and Google chat models, `tiktoken` for OpenAI, `heuristic`
+  elsewhere. On one Cyrillic line the difference is 9 estimated versus **19 actual**.
+
+  Two defects surfaced the moment the strategy was selected:
+
+  - The count endpoint was sent our canonical SLUG (`claude-haiku-4.5`) rather than the callable id
+    (`claude-haiku-4-5-20251001`), so the first model whose ids differed answered 404. The chat path
+    translates through the catalog; this one did not.
+  - A model marked `tiktoken` threw when the optional `tiktoken` peer was not installed, turning a
+    number into an error for anyone who had not opted in — while the guide promised the opposite.
+    The counter now falls back to the heuristic and says so once. Only that specific error is
+    caught: a network failure inside the count API still surfaces, because quietly answering with
+    an estimate when an exact count was asked for is how a wrong number gets believed.
+
+- **xAI hosted retrieval said "ready" before anything was searchable.** `indexStatus()` derived
+  readiness from the collection's `documents_count`, which reaches 1 the moment a document is
+  ATTACHED — measured at about five seconds before that document can actually be found. A caller
+  that polled exactly as the guide instructs still searched an empty index, and the model answered
+  from its own knowledge with nothing to say why.
+
+  It now reads the per-document status the API actually exposes (`DOCUMENT_STATUS_PROCESSING` ->
+  `PROCESSED`), so `ready` means searchable, and a partial failure reports `error` instead of a
+  quietly smaller corpus. xAI now passes the live hosted-retrieval scenario.
+
+  Found with it: `listCorpora()` threw a `TypeError` on every real response — the API returns
+  `{ collections: [...] }` and the code expected a bare array, as did the test fake. Both defects
+  survived because the unit tests were written against invented response shapes; they now use the
+  ones captured from the live API.
+
+- **The Google API key no longer travels in the URL.** Twelve endpoints — files, batch, media
+  generation, Imagen, Veo and the long-running-operation polls — sent it as `?key=`, so the
+  credential was copied into every access log, proxy log and telemetry span the request passed
+  through, and could leak through a `Referer`. They now send `x-goog-api-key`, which is what the
+  chat adapter was already fixed to do. One endpoint was sending it BOTH ways.
+
+  `google/realtime` still uses `?key=` and is the one documented exemption: it is a WebSocket
+  handshake and a browser cannot set a header on one. A test enumerates the exemptions and fails if
+  one becomes stale, so the next `?key=` cannot arrive quietly.
+
+  Verified live before the fixtures were re-frozen — google files, image, tts and batch all pass
+  with header auth — and the re-freeze was diffed pairwise: 21 artifacts changed, every one only in
+  that way.
+
+- **The cost ledger recorded a provider call that never happened.** `countTokens()` emitted its
+  zero-cost count-API entry whenever the provider was Anthropic or Google and a key was present —
+  that is INTENT. The counter picks its strategy from the catalog's `tokenizer.strategy`, and no
+  catalogued model declares one, so the heuristic answered and nothing was called. The entry is now
+  gated on the strategy that actually ran.
+
+- **A test that was describing the bug.** The count-API cost test stubbed `globalThis.fetch` and
+  handed the engine a `null` one — it could only pass while the count APIs bypassed the engine. It
+  now intercepts the engine's fetch and asserts the endpoint that was called.
+
+- **A Google hosted corpus was silently ignored.** `{ type: 'file_search' }` had no mapping in the
+  Gemini chain spec, so the tool was dropped from the request and the model answered from its own
+  knowledge, with no error anywhere. The live example asks a question only the uploaded document
+  can answer and got a plausible wrong number back. `fileSearch` is now mapped from the tool's
+  params, matching `Tool.fileSearch` in Google's own SDK.
+
+  The same call on OpenAI failed loudly instead (`Missing required parameter:
+  'tools[0].vector_store_ids'`): a hosted `asTool()` result has to be passed as the `params` of a
+  `file_search` builtin. The retrieval guide now shows that, having previously said "splice into
+  the provider's native call" without saying how.
+
+- **Hosted document uploads are reproducible.** A document with no `label` was named
+  `doc-<random-uuid>.txt`, so the same upload produced a different request every time: it could not
+  be asserted in a test, frozen in a fixture, or matched against a log, and a retried upload
+  arrived under a new name. The fallback is now derived from the document's content — the same fix
+  the xAI batch name got.
+
+### Removed
+
+- **`ModelInfo.wire`, `NormalizedRequest.wire` and the `ModelWire` type** (BREAKING, type-level
+  only). These carried per-model wire traits; `ModelInfo.wireSpec` carries the same knowledge and
+  carries it once. Two
+  representations of one fact drift, and this library has shipped two bugs from exactly that. See
+  MIGRATION.md — behaviour is unchanged and most codebases need no edit.
+
+  Removed with them, and never reachable from the package entry point: `anthropicThinkingShape`,
+  `anthropicAcceptsTopK`, `ANTHROPIC_ADAPTIVE_THINKING_MIN`, `ANTHROPIC_THINKING_BUDGETS`,
+  `DEFAULT_ANTHROPIC_THINKING_BUDGET`, `googleUsesThinkingBudget`, `GOOGLE_THINKING_BUDGETS`,
+  `GOOGLE_THINKING_LEVELS`.
+
 ## [2.3.0] — 2026-08-23
 
 ### Added

package/MIGRATION.md

@@ -1,3 +1,133 @@
+# Migrating to 3.0.0
+
+**Almost certainly no source changes.** One type member was removed, and it was one the SDK
+set for its own adapters to read — not something an application was ever expected to write.
+
+## `ModelInfo.wire`, `NormalizedRequest.wire` and the `ModelWire` type are gone
+
+`wire` carried per-model traits (`{ thinking, topK }`) that told an adapter which shape a model
+takes. `ModelInfo.wireSpec` — which names the wire spec that builds the request — now carries the
+same knowledge, and it carries it exactly once.
+
+That duplication was the point of removing it. Two representations of one fact drift apart, and
+this library has already shipped two bugs from precisely that: 2.2.1 sent Anthropic the retired
+`thinking` shape, and 2.2.2 sent Gemini tool schemas on the wrong field. Keeping `wire` alongside
+`wireSpec` would have been the same mistake with better tests.
+
+**What to do:** nothing, unless you read `.wire` off a catalog entry. If you did:
+
+```ts
+// before
+const shape = catalog.get('anthropic', model)?.wire?.thinking;   // 'adaptive' | 'budgeted'
+
+// after — the pin names the spec, and the spec defines the shape
+const spec = catalog.get('anthropic', model)?.wireSpec;          // 'anthropic/messages@4.7'
+```
+
+If you were SETTING `wire` on a custom catalog entry to steer an adapter, set `wireSpec` instead:
+
+```ts
+catalog.set('anthropic', 'my-model', { pricing: {}, wireSpec: 'anthropic/messages@4.1' });
+```
+
+**Behaviour is unchanged.** Every catalogued model produces the byte-identical request it produced
+in 2.3.0 — checked on every CI run against a corpus frozen from the 2.3.0 tag: 290 subjects across
+23 request shapes, on both the pinned and the id-derived route.
+
+## The catalog is loaded by default
+
+`createEngine()` and `LLMClient` now start with the bundled provider catalogs instead of an empty
+one. **Almost certainly no source change** — and if you were already passing `catalog: 'defaults'`,
+that still works and now says the same thing twice.
+
+What changes if you were NOT passing it: prices become known, token counts can use the exact
+strategies, and requests are built from the model's wire-spec pin rather than from a rule over its
+id. All three were falling back before, silently.
+
+```ts
+// before — an empty catalog unless you asked
+const engine = createEngine({ apiKeys });            // no pricing, no pins
+const engine = createEngine({ apiKeys, catalog: 'defaults' });  // the data
+
+// after — the data, unless you opt out
+const engine = createEngine({ apiKeys });            // the data
+const engine = createEngine({ apiKeys, catalog: false });       // no entries, on purpose
+```
+
+If you relied on an empty catalog — to be certain no bundled price was used, say — pass
+`catalog: false` (or `'empty'`).
+
+## The token-count APIs need the engine's fetch
+
+`AnthropicCountApi` and `GoogleCountApi` used to default their second argument to
+`globalThis.fetch`. That default is gone: the fetch is required, and it is an `EngineFetch` — the
+same request-object fetch every other adapter takes — rather than a WHATWG `(url, init)` one.
+
+**Almost certainly no source change.** `countTokens()` and `HybridTokenCounter` build these for you,
+and `countTokens()` passes `engine.fetch`. You only touch this if you construct one directly:
+
+```ts
+// before — went around the NetworkEngine entirely
+const api = new AnthropicCountApi(apiKey);
+
+// after
+const api = new AnthropicCountApi(apiKey, engine.fetch);
+```
+
+If you build a `HybridTokenCounter` yourself and want the exact count APIs, pass `fetch`:
+
+```ts
+new HybridTokenCounter({ catalog, countApiKeys, fetch: engine.fetch });
+```
+
+Without it the exact strategies are unavailable and counting falls back to the heuristic, with a
+warning — rather than quietly calling the provider outside the queue, the rate limiter, the retry
+policy and the telemetry, which is what the old default did.
+
+## `hooks.onAny` receives one event instead of `(name, ctx)`
+
+Only affects code that subscribes to the WHOLE event stream. `hooks.on('onCompletion', h)` — the
+named subscription — is unchanged.
+
+```ts
+// before
+hooks.onAny((name, ctx) => {
+  if (name === 'onCompletion') {
+    const c = ctx as { response?: { usage?: { inputTokens?: number } } };
+    record(c.response?.usage?.inputTokens ?? 0);
+  }
+});
+
+// after — `event.type` narrows `event.ctx`, so the cast is gone
+hooks.onAny((event) => {
+  if (event.type === 'onCompletion') {
+    record(event.ctx.response.usage?.inputTokens ?? 0);
+  }
+});
+```
+
+The old shape forced every subscriber to cast, and a cast keeps compiling after the field it names
+is renamed — which for a usage or cost field is a metric that silently reads zero. `HookEvent` is
+derived from `HookMap`, so a hook added later becomes a variant your `switch` is told about.
+
+## Google requests carry the API key in a header, not the URL
+
+Behaviour, not signature: no source change, and no key of yours moves. Twelve Google endpoints —
+files, batch, media, embeddings, count — used to append `?key=…` to the URL; they now send
+`x-goog-api-key`. Nothing to update unless something in your infrastructure reads the key OUT of
+the URL: an allowlist matching on the query string, a log scrubber written against `key=`, or a
+proxy that routes on it. Those stop seeing it, which was the point — a URL travels through logs,
+proxies and error reports that a header does not.
+
+## Nothing else was removed
+
+The band helpers that went with it — `anthropicThinkingShape`, `anthropicAcceptsTopK`,
+`googleUsesThinkingBudget`, and the thinking-budget tables — were never exported from the package
+entry point, and the `exports` map has always blocked deep imports, so no application could reach
+them. They now live as data in `src/wire/pins/`, which is what the Python and Rust ports read.
+
+---
+
 # Migrating to 2.0.0
 
 **Most codebases need no source changes.** The point of this library is that provider churn is our

package/dist/bus/hook-bus.d.ts

@@ -12,9 +12,19 @@
  *  swallow — emitters need to know if a critical handler (like ContextGuard
  *  abort) failed. Plugins that should never break the request must catch
  *  their own errors. */
-import type { HookHandler, HookMap, HookName } from './hook-map';
-/** Catch-all handler: receives the event name + context for EVERY emit. */
-export type AnyHookHandler = (name: HookName, ctx: unknown) => void | Promise<void>;
+import type { HookEvent, HookHandler, HookMap, HookName } from './hook-map';
+/** Catch-all handler: receives EVERY emit as one discriminated union.
+ *
+ *  It used to receive `(name, ctx: unknown)`, which pushed the type back onto the
+ *  subscriber — and the SDK's own telemetry adapter, the only consumer, answered
+ *  the way anyone would: `ctx as Record<string, unknown>`, then a cast per field —
+ *  26 of them in one method.
+ *  Renaming a context field left those reads compiling and silently `undefined`,
+ *  which for the token and cost fields means a metric that quietly goes to zero.
+ *
+ *  With `HookEvent`, `e.type` narrows `e.ctx` and those casts stop being possible
+ *  to write. */
+export type AnyHookHandler = (event: HookEvent) => void | Promise<void>;
 export declare class HookBus {
     private handlers;
     private anyHandlers;

package/dist/bus/hook-map.d.ts

@@ -621,3 +621,27 @@ export interface HookMap {
 }
 export type HookName = keyof HookMap;
 export type HookHandler<K extends HookName> = (ctx: HookMap[K]) => void | Promise<void>;
+/** One event, as a value. `HookMap` types a SUBSCRIPTION (`on('onCompletion', h)`
+ *  knows its own ctx); this types the STREAM, where the name is not known until
+ *  runtime and the payload has to travel with it.
+ *
+ *  Derived from `HookMap` rather than written out, so the 51 variants cannot drift
+ *  from the 51 hooks: adding an entry above adds a variant here, and a consumer
+ *  switching exhaustively over `type` stops compiling until it handles the new one.
+ *
+ *      hooks.onAny((e) => {
+ *        if (e.type === 'onCompletion') e.ctx.response.usage;   // narrowed
+ *      });
+ *
+ *  The payload stays nested under `ctx` instead of being spread onto the event.
+ *  Spreading would collide with the contexts that already carry their own `type`
+ *  field, and would copy an object on every emit — including the per-chunk ones. */
+export type HookEventOf<K extends HookName> = {
+    readonly type: K;
+    readonly ctx: HookMap[K];
+};
+/** The SDK's whole event stream as a single discriminated union — the portable
+ *  shape: a Rust enum, a Python tagged union, a TS union, all from one catalog. */
+export type HookEvent = {
+    [K in HookName]: HookEventOf<K>;
+}[HookName];