@combycode/llm-sdk 2.2.2 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,561 @@ 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/).
 
+## [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
+
+- **Every catalogued chat model is pinned to a wire spec.** `ModelInfo.wireSpec` names the spec
+  that builds that model's requests — `anthropic/messages@4.7`, `google/generate@2.5`,
+  `openai/responses`, and so on. All 289 chat models across five providers carry one.
+
+  The pin is what lets this SDK and the Python and Rust ports agree on a model without each
+  re-deriving its wire shape from the model id — the derivation that produced the 2.2.1 and 2.2.2
+  bugs.
+
+  Carried and validated, not yet authoritative: the hand-written adapters still build requests
+  from `wire` traits. Because that is two representations of one fact, and two representations
+  drift, a test drives the PINNED SPEC and asserts the request it produces matches what the traits
+  say the model takes. When the adapters become spec-driven in 3.0.0, `wire` goes away and that
+  test is what makes the swap safe.
+
+- **Wire specs ship in the repo** (`src/wire/`). 71 JSON specs describe how to talk to each
+  provider API — field names, enum values, defaults, versioned tool-type strings, which shape a
+  model version takes — covering every adapter the SDK has: chat, interactions, media, realtime,
+  embeddings, files and batch.
+
+  They exist so the Python and Rust ports consume one artifact instead of re-deriving the same
+  knowledge three times, and so a provider change is one reviewable diff rather than three code
+  changes. This is the knowledge that, living in regexes, produced the 2.2.1 and 2.2.2 bugs.
+
+  **Oracle, not yet authority:** the adapters remain hand-written, and a test
+  (`tests/unit/wire`) proves the specs and the adapters agree on every CI run — data that is
+  never executed rots. Making the specs authoritative is the 3.0.0 step.
+
+  They are not exported from `index.ts` and are tree-shaken out of `dist`, so they add **no bytes**
+  to the published package (verified: package size unchanged).
+
+- **Every catalogued chat model is checked against its pinned spec on every run.** The previous
+  pin test drove Anthropic and Google models only — 26 of 289. The other 263, 224 of them
+  OpenRouter, were covered by nothing stronger than "the pin names a spec that resolves", which a
+  typo satisfies. `tests/unit/wire/every-model-reproduces-its-adapter.test.ts` now builds 17
+  request shapes for every chat model, through the spec the CATALOG pins it to, and requires the
+  payload to equal the one the real adapter produces — ~4,900 comparisons, under a second.
+
+  The adapter is chosen from `preferredApi`, never from the pin. Choosing it from the pin is
+  circular and silently so: mis-pin an OpenRouter model to `openai/responses` and the adapter
+  moves with it, both sides agree, and the sweep stays green on a broken pin. It did exactly that
+  until a deliberate corruption caught it. Mis-pinning any single model in any of the five
+  providers now fails, as does a provider losing its pins entirely.
+
+- **A consumer example for traces** (`telemetry-traces`, in the examples corpus): subscribing with
+  `onTrace`, filtering by span type at the subscription rather than in the handler, head sampling,
+  keeping prompt content out, joining an inbound `traceparent`, naming a run with
+  `label`/`source`/`attributes`, and reading `client.routing`. The trace feed had no example at
+  all, which the quality gate's example-first check was reporting.
+
+- **Request builders on the media and realtime adapters.** These adapters used to assemble each
+  request *inside* the method that also fetched and parsed it, so the only way to see what the SDK
+  would send was to intercept the network. Construction is now separated:
+
+  - `GoogleMediaAdapter`: `buildImageRequest`, `buildEditImageRequest`, `buildAudioRequest`,
+    `buildVideoRequest`, plus the lower-level `buildImagenRequest` / `buildGenerateContentRequest`.
+  - `OpenAIMediaAdapter`: `buildGenerateImageRequest`, `buildEditImageRequest`, `buildAudioRequest`,
+    `buildVideoRequest`.
+  - Realtime: `buildConnectRequest` on both adapters, and free functions
+    `buildOpenAISessionUpdate` / `buildOpenAITurnFrames` and `buildGoogleSetupFrame` /
+    `buildGoogleTurnFrames` for the handshake and per-turn frames.
+
+  The public methods now call these, so the two cannot drift — and a test
+  (`media-request-builders.test.ts`) asserts that what a builder returns is byte-identical to what
+  its method actually sends.
+
+  Additive: no existing signature changed.
+
+- **The catalog now knows how to TALK to a model, not just what it can do.** `ModelInfo` gains a
+  `wire` block carrying per-model wire traits — which `thinking` shape the model accepts, whether
+  it takes `top_k` — and `LLMClient` resolves it onto every request as `NormalizedRequest.wire`.
+  Adapters read that instead of parsing the model id.
+
+  This is the gap behind two shipped bugs. The catalog already recorded that a model supported
+  reasoning; nothing recorded which of two incompatible `thinking` shapes it accepted, so adapters
+  matched on the id and got it wrong twice — in 2.2.1, and again in the 4.0 date-suffix defect
+  fixed this release. Wire knowledge is now reviewable data that can be diffed and generated,
+  rather than a regex nobody re-reads.
+
+  The bundled catalog carries `wire` for all 14 Anthropic and 12 Google chat models, generated
+  from the existing rules so behaviour is unchanged on day one. When the catalog is silent —
+  an engine running without one, or an uncatalogued model — adapters fall back to parsing the id
+  exactly as before, so nothing breaks. Removing that fallback is a later step, once every model
+  is pinned.
+
+- `EngineHandle.createClient(options)` — build an `LLMClient` bound to that engine. Added so
+  `plugins/internal-tools` can obtain a client without importing `createLLM` from the helpers
+  layer. Additive on a handle callers receive rather than implement.
+
+- `util/hash` — FNV-1a 32-bit, deterministic and dependency-free, for deriving stable short ids
+  from content instead of from a clock.
+
+### Changed
+
+- **The module graph is now a DAG.** Two dependency cycles between top-level layers were closed:
+  `llm <-> plugins` and `helpers <-> plugins`. They were harmless in TypeScript and are not
+  harmless in Rust, where crates cannot express a cycle, so they blocked the port.
+
+  Shared code moved DOWN rather than sideways: the model catalog and its bundled data now live in
+  `src/catalog/` instead of `src/plugins/model-catalog/` + `src/llm/providers/*/catalog.json`, and
+  image-source normalisation moved from `src/plugins/media/source-image` to `src/util/source-image`.
+  Where a lower layer genuinely needs a capability from a higher one it is now passed down instead
+  of imported up.
+
+  **No public API changed** — the package has a single root export and every moved symbol is
+  re-exported from the same place as before. A new test (`tests/unit/architecture/layers.test.ts`)
+  fails if any cycle returns.
+
+- **Internal cleanups carried over from the 1.0 backlog.**
+  - `buildContext` read `LLMClient`'s private `queueName` / `configName` / `cacheName` through
+    `as unknown as` casts, which compile happily and would silently yield `undefined` the day a
+    field is renamed. The client now exposes them deliberately as `client.routing`, so a rename is
+    a type error.
+  - Telemetry's ten exported types moved from the 1,225-line `telemetry.ts` to
+    `plugins/telemetry/types.ts`, matching the rest of the codebase. Re-exported from the old path,
+    so no import — public or internal — changed.
+  - `sseJson()` in `providers/_shared` replaces the one line every provider's stream parser
+    repeated verbatim.
+
+- **`providerOptions` is typed.** It was `Record<string, unknown>` — the one untyped hole in the
+  request, and so the one place a typo produced silence rather than an error:
+  `promtCacheOptions` type-checked and was simply never sent.
+
+  The new `ProviderOptions` interface documents every key an adapter actually reads
+  (`userProfileId`; `moderationPolicy`, `promptCacheOptions`, `reasoningMode`;
+  `responseModalities`, `speechConfig`, `imageConfig`, `translationConfig`, `cachedContent`;
+  `openrouter`), derived from the read sites rather than invented. Two `as` casts at those sites
+  became unnecessary and were removed.
+
+  **Not breaking:** the index signature stays, so an unmodelled key is still accepted — providers
+  ship parameters before the SDK models them, and refusing those would make the escape hatch
+  useless. What changed is that the keys we do know are checked and discoverable.
+
+- **`AgentLoop.complete()` and `stream()` no longer duplicate their scaffolding.** The two are the
+  same loop with different plumbing, and they had drifted into near-duplicates — 167 identical
+  lines across ~560. Five shared pieces are now extracted: `recordRunError`, `resolveFinalText`,
+  `buildFinalResponse`, `settleRun`, and `buildStepOptions`.
+
+  This is not tidying. The `ctx` block in `buildStepOptions` is what stops one conversation
+  arriving at a collector as several unrelated traces; duplicated, a fix to one path would have
+  left the other silently splitting. The same applies to the run's final-text rules and its
+  error reporting.
+
+  `complete()` 303 -> 234 lines, `stream()` 261 -> 209, identical shared lines 167 -> ~118.
+  Behaviour unchanged: all 1,953 tests pass untouched.
+
+### Fixed
+
+- **Anthropic 4.0 models were handed the 4.6+ `thinking` shape.** `anthropicThinkingShape()`
+  parsed a model id with `/^claude-[a-z]+-(\d+)(?:[-.](\d+))?/`, so an id carrying a release date
+  but no minor version read the date AS the minor: `claude-opus-4-20250514` became major 4 /
+  minor 20250514, cleared the `>= 4.6` test, and was sent `thinking: {type:'adaptive'}` — the
+  opposite of what the file's own `ANTHROPIC_ADAPTIVE_THINKING_MIN = {major:4, minor:6}` says.
+
+  This never shipped a failure: `claude-opus-4-20250514` and `claude-sonnet-4-20250514` are the
+  only affected ids and both are `active: false` in the catalog (deprecated 2026-05-14). It is
+  nonetheless the 2.2.1 regression in mirror image, so it is fixed rather than left latent. The
+  minor is now bounded to one or two digits and must not be followed by another digit. Checked
+  against every id in the catalog plus aliases and future-shaped ids (`claude-opus-4-10`,
+  `claude-sonnet-6-1-20270101`): exactly those two change classification, the other 17 are
+  untouched.
+
+- **xAI batch creation was not reproducible.** The create call named the batch
+  `` `batch_${Date.now()}` ``, which made it the only request in the provider surface that was not
+  a pure function of its input: it could not be asserted in a test or reproduced from a log, and a
+  retried create produced a second batch under a different name that nothing could deduplicate.
+  The name is now derived from the batch contents, so identical submissions produce identical
+  requests and differing ones still differ.
+
+- **`google/files` rejected Google's own resource-name format.** `delete()` and `getInfo()`
+  normalised the file id only when it contained `/files/` *with* a leading slash — true of the
+  full `uri` this adapter returns from `upload()` and `list()`, and false of `files/abc`, the
+  canonical `name` the Google API itself returns. Passing that back produced
+  `/v1beta/files/files/abc` and a 404.
+
+  It never broke the library's own round-trip, which is why it survived: the only way to reach it
+  was to use the provider's own id format. All three forms — full uri, `files/abc`, and a bare
+  name — now normalise to the same request.
+
 ## [2.2.2] — 2026-08-17
 
 ### Fixed