@combycode/llm-sdk 1.6.1 → 2.0.0

package/CHANGELOG.md

@@ -4,7 +4,524 @@ 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]
+## [2.0.0] - 2026-08-09
+
+**Upgrading:** three things can require action, and none of them is a provider change — that is the
+point of the facade. (1) Node **22+** is now required. (2) `tiktoken` is an optional **peer**: run
+`npm i tiktoken` only if you use exact local OpenAI token counting. (3) If you switch exhaustively
+over `FinishReason` or `ContentPart` without a `default` branch, add one — both are open by design
+(CONSTITUTION R1) so future provider values arrive additively instead of breaking your build. The
+only changed signature is `OpenAITranscriptionAdapter.transcribe()`, which now returns an object;
+read `.text`. The `transcribe()` helper is unaffected. Full detail: [MIGRATION.md](./MIGRATION.md).
+
+### Changed — packaging (install/runtime level; no source change for consumers)
+
+- **Node floor raised to `>=22`** (was `>=18`). Node 18 and 20 are both end-of-life; 22 is also the
+  floor `openai-node` 7 adopted.
+- **`tiktoken` is now an OPTIONAL PEER dependency**, not an `optionalDependency`.
+  `optionalDependencies` means *"do not fail the install if this package fails to build"* — npm
+  installs it regardless, so every consumer received its ~5.6 MB wasm file. **If you use exact
+  OpenAI token counting, run `npm i tiktoken`**; the error thrown when it is missing names the
+  package and the alternatives (count-API and heuristic counters need no extra packages).
+- **The wasm no longer lands in consumer bundles.** The dynamic import used a string literal, which
+  every bundler resolves during module-graph construction — so the blob was emitted even for code
+  paths that were never reached (one consumer reported it as **88% of their production output**).
+  `sideEffects: false` cannot prevent this: emitting a dynamic-import chunk is a graph-resolution
+  outcome, not dead-code elimination. The specifier now lives in a variable, opaque to bundlers and
+  resolved identically at runtime. Verified with a control — a literal import emits a 5.3 MB
+  `.wasm`; the shipped build emits none, even when the consumer imports `ContextMeasurer` directly
+  and has `tiktoken` installed.
+- **`tiktoken` still works in the browser.** It ships a wasm/ESM build that bundlers resolve for
+  browser targets, so it is deliberately *not* stubbed out of `index.browser.js`.
+- **`HybridTokenCounter` builds its tiktoken counter lazily**, on first route to that strategy,
+  rather than in the constructor.
+- **The "zero dependencies" claim is now qualified** as *zero **required** runtime dependencies*.
+  `dependencies` genuinely is empty, but a consumer reading only that field concluded there were no
+  runtime packages at all.
+
+### Added — MCP speaks both protocol eras
+
+`mcp` 2.0.0 shipped the **2026-07-28 revision**, which is not additive: it deletes the `initialize`
+handshake, the session id, and the whole server→client back-channel. Real servers are still almost
+entirely on 2025-11-25, so this is **dual-era or it is a regression** — both wires are supported and
+neither is preferred.
+
+**Verified against a real server, on every transport.** The modern wire was developed against our
+own test doubles, which is not evidence: a shape that satisfies a fake can still be rejected by a
+real implementation. Before release the whole surface was run against the official
+`mcp` 2.0.0 Python server — negotiation, tools, resources, prompts, MRTR, `subscriptions/listen`
+with live change events, result caching and era gating — over **stdio, Streamable HTTP and
+WebSocket**, plus a real 2025-11-25 server (DeepWiki) to prove the fallback. That exercise found
+six defects that no unit test could have caught, four of which failed *silently*: the per-request
+`_meta` identity envelope was missing (on ordinary requests, and separately on the long-lived
+`subscriptions/listen` POST, where the rejection surfaced as the stream simply ending — so `listen()`
+returned a subscription that looked alive and delivered nothing); `connectMcp` never forwarded
+`cacheResults`, making the opt-in cache a no-op; the discover probe omitted the
+`MCP-Protocol-Version` header that modern servers route on; the routing headers keyed off an era
+that is not yet set during the probe; and the long-lived POST accepted only `text/event-stream`,
+which a modern server answers with `406`. All are fixed and pinned by regression tests.
+
+- **`server/discover` negotiation with handshake fallback.** `ConnectMcpOptions.protocolMode`:
+  `'auto'` (default) probes the modern wire and falls back to `initialize`; `'legacy'` skips the
+  probe entirely (byte-identical to 1.x); a version string adopts that revision directly.
+- **The fallback is a denylist, not an allowlist.** *Every* JSON-RPC error falls back to the
+  handshake, except a `-32022` whose `supported` list is modern-only and shares nothing with us —
+  a genuine incompatibility that must surface rather than be papered over. **Transport and network
+  errors are never treated as an era verdict**: silently downgrading the wire because a socket
+  blipped would be the worst available failure mode.
+- **`McpClient.info` is unchanged on both wires.** A modern server has no `initialize` result, so
+  one is synthesised from the discover result and its `_meta` server-info stamp. Callers never
+  branch on the era (CONSTITUTION.md R2 — absorb the difference, never expose a union). The stamp is
+  display-only per spec, so absent *or* malformed degrades to a placeholder instead of failing the
+  connection.
+- **New (additive):** `McpClient.protocolVersion`, `.era`, `.discoverResult`, the
+  `McpDiscoverResult` type, and the version registry (`MCP_KNOWN_PROTOCOL_VERSIONS`,
+  `mcpEraOf`, …). Versions are treated as an **enumerated set, not an ordered scalar** — comparing
+  `'zzz' > '2025-11-25'` is true and meaningless, so era questions go through the registry.
+- **Methods the revision removed are gated by era.** `logging/setLevel` and `resources/subscribe`
+  throw on a modern session with a message naming the negotiated version and the replacement,
+  instead of letting the server answer a bare `-32601`. The `ping` keep-alive is not started on a
+  modern session. All of them are untouched on a handshake session.
+- **A 4xx carrying a JSON-RPC error body no longer loses it.** The HTTP transport collapsed every
+  4xx into `ConnectionClosed`, which discarded exactly the `-32022` that negotiation depends on — a
+  modern-only server looked like a dead connection.
+- New error codes: `HeaderMismatch` (-32020), `MissingRequiredClientCapability` (-32021),
+  `UnsupportedProtocolVersion` (-32022).
+
+**Multi-round-trip requests (MRTR, SEP-2322)** — the modern replacement for the back-channel. Where
+a handshake-era server *pushes* a `sampling/createMessage` at us mid-call, a 2026-07-28 server
+*returns* `resultType: 'input_required'` with the questions it needs answered, and the client
+re-issues the same call carrying the answers plus the server's opaque `requestState`.
+
+- **One handler serves both wires.** MRTR is dispatched through the same `onServerRequest` path as
+  a pushed request, so a caller who wired up sampling/elicitation/roots once gets it on either wire
+  without knowing which is in play.
+- **`McpCallResult` did not become a union.** Upstream models this as a separate
+  `InputRequiredResult`, which would break every consumer reading `.content`. We attach
+  `resultType` / `inputRequests` / `requestState` as optional fields instead (CONSTITUTION.md R2).
+  An **absent `resultType` reads as `'complete'`**, so every pre-2026 result behaves exactly as
+  before and costs no extra round-trip.
+- Applied to `tools/call`, `prompts/get` and `resources/read`. `requestState` is echoed back
+  byte-exact and never inspected.
+- A leg carrying state but no questions backs off (50 ms doubling to a 250 ms cap, reset by any leg
+  with real questions) rather than spinning against the server.
+- `inputRequiredMaxRounds` (default **10**, matching the other SDKs) bounds the loop, because a
+  handler that never satisfies the server would otherwise retry forever.
+
+**`subscriptions/listen` (SEP-2575)** — the single change-notification stream that replaces
+`resources/subscribe` and the standalone notification channel at 2026-07-28.
+
+- `McpClient.listen(filter, onEvent)` returns an `McpSubscription`. Every kind is **opt-in**
+  (`toolsListChanged`, `promptsListChanged`, `resourcesListChanged`, `resourceSubscriptions[]`) and
+  the server acknowledges with the subset it actually honoured — which **can be narrower than what
+  was requested**, so `subscription.honored` / `isHonored(kind)` is worth checking rather than
+  assuming. Frames are attributed by the `io.modelcontextprotocol/subscriptionId` stamp, so frames
+  for another subscription are ignored.
+- Refused with a clear error on a handshake session, which keeps `subscribeResource()` the right
+  answer there instead of silently returning a subscription that never fires.
+- **Works on every transport** — stdio, WebSocket and Streamable HTTP. On HTTP a listen is a POST
+  whose *response body* is the long-lived stream, so it goes through the streaming fetch rather than
+  the buffered POST path (which would surface frames only once the stream closed — i.e. never, for
+  a healthy subscription). Frames route identically on all three, so the client sees no difference.
+- **The end of a stream is observable.** `subscription.active` / `.ended` report whether the stream
+  is still live and, if not, the error that killed it — a rejected subscription, a dropped
+  connection, or a clean server-side teardown. A subscription that silently stopped delivering is
+  otherwise indistinguishable from one where nothing has changed yet; failures also surface on the
+  `onMcpError` hook. `close()` on the client tears down every open stream.
+
+**Hardening**
+
+- **The stdio read buffer is bounded** (`maxBufferSize`, default **10 MB**, matching mcp-ts 1.30).
+  JSON-RPC over stdio is newline-delimited, so a server that never emits `\n` — a crash dump, a
+  binary blob on the wrong stream, a runaway log line — grew the buffer until the process died.
+  The limit applies to a single *unterminated* line, so a large burst of complete messages is
+  unaffected; on overflow the pending requests fail with a message naming the likely cause.
+- **`Content-Type` is compared by media-type essence, not substring.** `contentType.includes(...)`
+  routed anything merely *containing* `text/event-stream` — e.g. `application/json;
+  profile="text/event-stream"` — into the SSE parser.
+- **RFC 9207 `iss` validation** on the OAuth authorization response, checked **before** the code is
+  redeemed. This is the mix-up-attack defence: without it a malicious authorization server can hand
+  back a code minted by a different server and have the client replay the user's credentials
+  against it. Comparison is exact string equality per §2.4 — deliberately *not* URL-normalised,
+  since that leniency is what an attacker looks for. A **missing** `iss` is rejected when the server
+  advertises `authorization_response_iss_parameter_supported`, otherwise stripping the parameter
+  would skip the check. Pass it via `finishMcpAuth(..., { iss })`; optional, so existing callers
+  keep working.
+- **`application_type: 'native'` is sent at dynamic client registration** (SEP-837). MCP clients are
+  normally local processes with a loopback redirect, and some authorization servers apply stricter
+  redirect-URI rules when the type is left to be guessed as `web`. An explicit value from the caller
+  still wins.
+- **The WebSocket transport is kept** and now documents itself as non-standard. Upstream removed
+  theirs as "never part of the MCP specification"; ours is public API we shipped, and an upstream
+  deletion is not our deletion (R7). It is also duplex, so it supports `subscriptions/listen` today.
+
+**Result cache hints (`ttlMs` / `cacheScope`)** — opt-in via `cacheResults`, off by default.
+Settable on `connectMcp(config, { cacheResults: true })` as well as on `McpClient` directly, along
+with `inputRequiredMaxRounds`.
+
+- Honours the server's freshness hint on `tools/list`, `prompts/list`, `resources/list`,
+  `resources/templates/list` and `resources/read`. **A server that sends no hints caches nothing**,
+  so this is a no-op against every pre-2026 server.
+- **`ttlMs: 0` means "immediately stale"** — a real instruction, not a missing value to be replaced
+  with a default.
+- A paginated list is only as fresh as its shortest-lived page, so the effective TTL is the
+  **minimum** across pages.
+- Entries are dropped on the matching `*_changed` notification **before** the caller's handler
+  runs, so a handler that re-lists synchronously never reads a stale entry. A
+  `notifications/resources/updated` drops only the named resource.
+- `cacheScope` is recorded but never used to widen sharing: this cache lives inside one client with
+  one credential, where `public` buys nothing.
+
+### Changed — `FinishReason` is now an OPEN union
+
+- **`FinishReason` = `KnownFinishReason | (string & {})`.** Providers keep inventing terminal
+  states — four did so in a single upstream cycle — and against a closed union every one of those is
+  a breaking change for **every** consumer, including consumers of providers that changed nothing.
+  Opening it is what CONSTITUTION.md R1 exists for, and it means this is the **last** time this type
+  breaks anyone. Write a `default` branch; use `KnownFinishReason` for the documented set alone.
+- **New known value `'malformed_tool_call'`** — the model tried to call a tool and produced
+  something unusable. Distinct from `error` (the request failed) and `tool_use` (a call we can
+  run), because this one is *recoverable*.
+- **Google's `MALFORMED_FUNCTION_CALL` is now mapped.** It previously wasn't mapped at all, so it
+  fell through to `'stop'`: a turn where the model failed to produce a usable tool call looked like
+  a clean finish with no content.
+
+### Added — agent + network
+
+- **`reflectAndRetry` on `AgentLoop`** (google-adk 2.6 `ReflectAndRetryModelPlugin`).
+  Self-healing recovery from a model failure the model itself can fix: it receives structured
+  guidance naming the attempt and forbidding an identical retry, then the step runs again within a
+  bounded budget. **Off unless configured** — a retry costs a real request.
+  - **Not a network retry.** The engine already retries transport failures; this is for a request
+    that *succeeded* and came back unusable, which resending unchanged would never fix.
+  - The failed turn is **not appended to history**, so the model never learns from its own broken
+    output; usage from it *is* counted, because a wasted turn still costs money.
+  - Counts **consecutive** failures, so an agent that recovers and fails again later gets a fresh
+    budget rather than inheriting a spent one.
+  - `throwIfExceeded` (default `true`) decides raise-vs-return when the budget is spent; the error
+    names the option so the alternative is discoverable.
+
+- **`checkProvenance()`** — detect provider provenance signals in a file (C2PA manifest, SynthID
+  watermark) via OpenAI's new `POST /v1/content_provenance_checks`. Bytes in, structured verdict
+  out, same shape as `moderate()`, with an honest-zero cost entry so the ledger records the call.
+  It is the only "was this AI-generated" primitive any tracked SDK ships.
+  - The result separates **`detected`** from **`trusted`**, and the docs say why: signals are
+    strippable — a re-encode, crop or screenshot usually removes them — so `detected: false` is
+    absence of evidence, not evidence a human made the file. Only a detected manifest that
+    *validated* is a positive statement.
+  - `detected` is true if ANY signal fired: audio carries SynthID only, so requiring both schemes
+    would report every audio file as clean.
+- **`AnchoredStrategy`** for ContextGuard — one growing scratchpad instead of a chain of summaries
+  (ported from google-adk 1.5 `AnchoredContextCompactor`). `LayeredStrategy` emits a new summary
+  per compaction, so old facts get summarised repeatedly and drift; anchored merges each compaction
+  into a single head entry, so every fact is summarised from raw text exactly once. The trade is
+  stated in the file: one anchor means one blast radius.
+  - **Never splits a tool call from its result.** The retain boundary walks backwards past a
+    `tool_result` whose `tool_call` would be cut away — several providers reject an orphaned
+    result outright and the rest silently misread it.
+  - **A summariser returning nothing declines rather than dropping entries**: trading a context
+    overflow for silent data loss is strictly worse.
+
+- **`toolNameCollisionPolicy`** on `AgentLoop` (`'warn'` default, `'error'`). Tools are registered
+  in a map keyed by function name / builtin type, so two tools sharing a key meant one **silently
+  replaced** the other and the model never saw it — surfacing much later as "the model called the
+  wrong tool", with nothing in the logs pointing at the cause. `'warn'` keeps last-write-wins (an
+  app relying on a deliberate override still works — R4) but emits an `onWarning`
+  (`code: 'tool_name_collision'`) naming the key and which tool lost; `'error'` throws at
+  construction or `addTool()`, before the model is called. Re-registering the *same* tool object is
+  not a collision.
+- **Per-request retry overrides** — `HttpRequest.retry` (`maxRetries`, `totalTimeoutMs`,
+  `attemptTimeoutMs`, `maxRetryAfterMs`, `backoff`). A queue's retry policy is shared by every call
+  on it, so a one-off that needs to be more or less patient — a long batch submit, a health check
+  that should fail fast — previously had to accept the shared policy or get its own queue. Mirrors
+  Google moving `retryOptions` from client-level to per-request `HttpOptions` (google-ts 2.15).
+  `perKind` deliberately stays queue-level: one request cannot redefine which error classes are
+  retryable for everyone sharing the queue. Precedence is per-request → per-kind → queue default.
+
+### Added — OpenAI Responses parity
+
+- **Assistant `phase` (`commentary` | `final_answer`)** on `TextPart` and on streamed text events.
+  Codex-family models narrate before answering; `response.text` concatenates both, so **an agent's
+  final output used to include its own thinking-out-loud**. `AgentLoop` now derives its answer with
+  the new `finalAnswerText()` helper, which drops commentary. `response.text` and `contentText()`
+  are unchanged — callers who want everything still get everything.
+  - Open union (R1), and `finalAnswerText` excludes only what is explicitly `'commentary'` rather
+    than keeping only `'final_answer'`: the day a provider adds a third phase, an allow-list would
+    silently drop the answer.
+  - Streaming carries it too. `phase` is announced once on `response.output_item.added` and belongs
+    on every delta of that item, so the parser keeps per-stream item→phase state; concurrent streams
+    cannot leak phases into each other. Commentary is still yielded to the consumer (a UI may well
+    want to render it live) and is preserved in the assembled content as its own phase-tagged part.
+  - Nothing is inferred: a model that reports no phase produces parts with no phase, exactly as
+    before.
+- **`name` + `namespace` on `function_call_output`.** The tool name is taken from the matching
+  call — tracked across messages while building the input, never invented, so a result with no
+  matching call simply omits it. `ToolResultPart.namespace` round-trips the namespace of a
+  namespaced tool. Probe-verified 2026-08-06: accepted, and a non-string `namespace` is rejected,
+  so the fields are validated rather than tolerated.
+
+### Added — programmatic tool calling (the model writes code that calls your tools)
+
+A model can now write a short program that orchestrates your tools itself, instead of
+emitting one call at a time and waiting for each result. Previously the `program` items
+in the response were dropped on the floor.
+
+- **`ToolCaller` on `ToolCallPart` and `ToolResultPart`** — `{ type: 'direct' | 'program',
+  callerId? }`. Absent means what it always meant (the model called the tool itself), so
+  nothing changes for existing code. Open union with an optional payload rather than
+  `{type:'direct'} | {type:'program', callerId}` (R1 + R2), so a future caller kind is
+  additive; an unknown type is preserved rather than flattened to `direct`.
+- **`ProgramCallPart` (`program_call`) and `ProgramResultPart` (`program_result`)** —
+  the code the model wrote, and what it returned. The code is plain readable JavaScript
+  and worth surfacing: it is the plan the model is executing.
+- **`allowedCallers` is now enforced locally**, not only by the provider. A tool without
+  it is `direct`-only, so model-written code cannot reach a tool that never opted in. A
+  violation denies that one call with an error result to the model — the way a guardrail
+  trip does — rather than ending the run.
+- **Round-tripping is the whole feature**, and three wire rules make it work (all found
+  live, none of them in any SDK's types):
+  - The `program` item is **rejected without the `reasoning` item that produced it**, so
+    that item is captured and re-emitted with it.
+  - **Dropping the program item is worse than an error**: the model silently re-emits the
+    program and runs it again from the start.
+  - `program_output` **requires its `id`** when replayed as history — unlike
+    `function_call_output`, which needs none. Without it a follow-up question 400s on a
+    conversation that had just succeeded.
+- **Availability, checked model by model:** of the 53 gpt-5 / o3 / o4 / codex models
+  visible on the test account, only the **`gpt-5.6` family** (`luna`, `sol`, `terra`)
+  accepts the `programmatic_tool_calling` tool. Every other one returns
+  *"Tool 'programmatic_tool_calling' is not supported with <model>"*.
+
+### Added — structured transcription
+
+`transcribe()` returned `{ text }` and nothing else, so segments, speakers and word timings that
+the provider had already computed were parsed and thrown away.
+
+- **New request options:** `keywords` (spelling control for names and jargon), `languages`
+  (candidate languages when the language is unknown), `wordTimestamps`, and `diarization`.
+- **New response fields, all optional:** `segments` (with `speaker` when diarizing), `words`,
+  detected `languages`, and `durationSeconds`. **`text` stays required** (R3), so existing code is
+  untouched — the additions appear only when the chosen model produces them.
+- **Behaviourally verified, not just accepted** (E2). `keywords` changes the transcript: an invented
+  name that comes back as *"Zalbrequist"* without it comes back as *"Zylberquist"* with it, on
+  identical audio. `languages` changes what the model reports detecting, and an invalid code is
+  rejected. Both are `gpt-transcribe`-only; word timings are `whisper-1`-only; speaker labels are
+  `gpt-4o-transcribe-diarize`-only. **No model returns speakers and word timings together**, so
+  combining `wordTimestamps` with `diarization` throws before any request is sent.
+- **Model-gated options are still sent.** A field the chosen model rejects produces a 400 naming
+  the parameter, rather than being dropped on our side — the caller learns their keywords did
+  nothing (R4: gating is internal, but silence is not a gate). On generateContent providers, which
+  have no structured endpoint at all, the same request emits an `onWarning`
+  (`transcription_option_unsupported`).
+- **Transcription cost is now measured, not estimated.** These models return the audio duration
+  they billed for (`usage.seconds`, or a top-level `duration`), which is used when the caller
+  supplies none. Previously a non-WAV file with no `audioDurationSeconds` could only produce an
+  honest zero.
+- **Google's equivalent is deliberately absent.** `audioTranscriptionConfig` is accepted *and
+  type-validated* by the Gemini Developer API and then completely ignored: a two-speaker round-trip
+  returned a response structurally identical to the control — no `speakerLabel`, no `words[]`
+  anywhere (2026-08-09). It is the second confirmed accepted-but-inert field after `top_k`. Shipping
+  it on the strength of the green probe would have meant a diarization feature that silently
+  returns nothing.
+
+**Breaking (2.0):** `OpenAITranscriptionAdapter.transcribe()` returns
+`OpenAITranscriptionResult` instead of `string`; read `.text`. The `transcribe()` helper is
+unaffected — it already returned an object.
+
+### Fixed — correctness
+
+- **Parallel tool calls were broken on every chat-completions backend.** The loop answers a round
+  of parallel calls with one tool message holding a `tool_result` part per call, and this API wants
+  a separate `{role:'tool'}` message per `tool_call_id` — but only the **first** was emitted. Every
+  call after the first went unanswered and the provider rejected the whole request with
+  *"No tool output found for function call <id>"*. Affected OpenRouter and any use of
+  `api: 'completions'` on OpenAI/xAI; the Responses path was always correct. Present in 1.7.0 and
+  earlier; found by running the examples corpus, not by a unit test.
+- **`serviceTier: 'fast'` is actually sent to OpenAI.** The value shipped in openai-ts 7.x but was
+  missing from our known-tier set, so `openaiRequestTier('fast')` fell through to `'auto'` — a
+  caller asking for Fast mode silently got the project default, with no error and no warning.
+  Probe-verified on `gpt-5.5`: `fast` accepted, `hyperfast` rejected, so the value is validated
+  rather than merely tolerated. Applies to Responses and chat-completions.
+- **A `Retry-After` longer than we will honour now fails fast instead of parking the request.** New
+  config `RetryConfig.maxRetryAfterMs` (default **120s**). Previously an un-capped value was obeyed
+  verbatim: `Retry-After: 86400` held the request for a day, which from the caller's side is
+  indistinguishable from a hang. Worse, on the rate-limit path it also paused the **entire**
+  limiter — every request on that queue, not just the one that was throttled. Both paths are now
+  clamped, and an over-cap value is treated as a refusal rather than a delay.
+- **`Retry-After` parsing hardened.** The HTTP-date form (RFC 9110) is now parsed instead of being
+  silently ignored, and malformed values (`NaN`, negative, non-finite, a past date) are discarded
+  rather than propagated — `setTimeout(fn, NaN)` fires immediately, which turned one bad header
+  into an instant retry storm.
+
+### Unchanged, deliberately
+
+- **Google Interactions keeps sending `temperature` and `top_p`.** google 2.15 deleted both from its
+  Interactions `GenerationConfig` type, which resembles the pattern behind two earlier live
+  breakages — but the wire disagrees: probed 2026-08-06 on `gemini-3.6-flash`, both are accepted
+  (200) and *validated* (`"warm"` / `-7` → 400). The removal is SDK-typing-only; stripping them
+  would have been the regression. Recorded at the call site so a later cycle does not "fix" it.
+
+---
+
+Upstream reconciliation for the 2026-07-27 clone refresh (10 SDKs). This batch is dominated by
+**terminal-state correctness**: three providers widened response enums that our adapters silently
+flattened to `'stop'`, so a caller could not distinguish a refusal, a context overflow, a queued
+interaction or an outright failure from a clean finish.
+
+### Fixed
+- **Google Interactions no longer sends `cached_content`.** google 2.13 removed it from the
+  Interactions request model and the endpoint now hard-rejects it — live-probed:
+  `400 Unknown parameter 'cached_content'`. Any call passing `providerOptions.cachedContent` on
+  Interactions failed outright. The passthrough **moved to `generateContent`**, which still accepts
+  and validates it (top-level `cachedContent`), so the capability is preserved rather than dropped.
+- **Anthropic `refusal` → `finishReason: 'content_filter'`** (was `'stop'`). A safety decline is a
+  block, not a clean finish; it now lines up with every other provider's block signal. The refusal
+  category enum also gained `general_harms` (anthropic 0.115).
+- **Anthropic `model_context_window_exceeded` → `finishReason: 'length'`** (was `'stop'`), on both
+  the buffered and streamed reason maps.
+- **OpenAI Responses `status: 'failed'` → `finishReason: 'error'`** (was `'stop'`), and `cancelled`
+  → `'error'`. A Responses call can fail *inside a 200*, so there was no exception to catch and the
+  caller silently received an empty success.
+- **Google Interactions `queued` no longer ends a stream.** The status is non-terminal, but the
+  stream parser emitted a terminal `done` for it, truncating the run.
+
+### Security
+- **`TelemetryAdapter` can redact provider error text.** New option
+  `includeSensitiveData` (default `true` — unchanged behaviour, and the same default as the OpenAI
+  Agents SDK's `trace_include_sensitive_data`). A provider's `error.message`/`error.raw` can echo
+  request content back (a refusal quotes the prompt, a validation error names the field and value),
+  and we stored it verbatim. With `includeSensitiveData: false` the message becomes `***REDACTED***`
+  and `raw` is dropped, while `name`/`code`/`status` are kept so traces stay triageable. URLs and
+  headers were, and remain, always redacted.
+
+### Fixed (hardening)
+- **SSE streams are now cancelled, not just unlocked.** `parseSSEStream` released the reader lock in
+  its `finally` but never cancelled the body, so a consumer that broke out early (abort, error, or a
+  `break` after the first token) left the HTTP response open until GC. Verified live on Anthropic,
+  OpenAI and Google: full streams unchanged, early `break` tears down cleanly.
+- **Non-replayable request bodies are never retried.** A streamed body is consumed by the first
+  attempt, so a retry would send an empty/partial body. Our own `rawBody` callers all pass FormData
+  or bytes (replayable), so this is a guard against a caller-supplied stream rather than a live bug.
+- **Case-insensitive response-header lookup.** `google/files.ts` guessed three casings of
+  `x-goog-upload-url` and would have missed any fourth. Header reads now go through one shared
+  `header()` helper in `util/http` (de-duplicated with the private copy in `llm/files/retrieve.ts`).
+
+### Added
+- **`topK` and `seed` sampling options.** Both were reachable on several providers and exposed by
+  none of our surface — parity gaps found by the new feature-matrix audit and closed the same day.
+  Each is emitted **only where the wire accepts it**, verified by live probe rather than inferred:
+  `topK` → Anthropic, Google (generateContent *and* Interactions), xAI chat, OpenRouter chat;
+  dropped for OpenAI, which defines no top-k. `seed` → OpenAI **chat-completions**, Google (both
+  surfaces), xAI (chat *and* responses), OpenRouter chat; dropped for Anthropic and OpenAI
+  **Responses**, which both reject it (400). Sending either to a surface that refuses it is a hard
+  error, so the gating is locked by unit tests and was live-verified end to end.
+- **`docs/feature-matrix.json` — the parity matrix.** Every capability an official SDK exposes, how
+  each provider spells it, and where we stand, with citations into the version-pinned clones.
+  `scripts/validate-feature-matrix.mjs` runs as part of `bun run lint` and fails the build on a
+  broken citation, an unexplained `partial`/`beta`/`by-design`, or a duplicate id. It backs the
+  site's comparison page and is maintained by the upstream-update cycle.
+- **`FinishReason` gains `'pending'`** — non-terminal: the provider accepted the request but has not
+  produced a completion (Google Interactions `queued`, OpenAI Responses `queued`/`in_progress` in
+  background mode). Treat as "poll/retry", never as a result. *Additive union member: exhaustive
+  `switch` statements over `FinishReason` should add a case.*
+- **`CompletionResponse.error?: { code?, message? }`** — populated when `finishReason === 'error'`,
+  carrying the provider's own failure detail (e.g. OpenAI's new `data_residency_mismatch` code,
+  openai 6.49). Optional field; absent unless the provider reported a failure.
+- Documented the OpenAI `reasoning.context` default (the `gpt-5.6` family defaults to `all_turns`,
+  earlier models to `current_turn`).
+- **`itemId` on `text` / `thinking` stream events.** OpenAI Responses reports which output item a
+  delta belongs to (`item_id`); a turn can interleave deltas from several items, so consumers that
+  reassemble per item — rather than concatenating into one string — now can. Optional and additive:
+  ignoring it gives exactly the previous behaviour, and providers that report no item id (chat
+  completions) simply omit it. Live-confirmed present on every delta from the Responses API.
+
+## [1.7.0] - 2026-07-16
+
+### Added
+- **Video extend + edit (xAI grok-imagine-video).** `VideoGenRequest` gains `sourceVideo?: DataSource`
+  and `params.videoMode?: 'extend' | 'edit'`. When a source video is present the xAI adapter routes to
+  the right endpoint instead of plain generation: `extend` (default) → `POST /v1/videos/extensions`
+  (continues from the last frame; takes `duration`, ignores aspect/resolution), `edit` →
+  `POST /v1/videos/edits` (prompt + video only). The clip is passed as a public URL, a Files-API id, or
+  an inline base64 data-URL. `MediaCapabilities` gains `videoExtension`; `MediaOutput.generateVideo`
+  throws if a `sourceVideo` is sent to a provider that doesn't support it (rather than silently
+  generating). `generateVideo(req)` is unchanged — the new fields flow through. Verified live end-to-end
+  on `grok-imagine-video`: generate → extend → edit all return video bytes. (Note: extend/edit require
+  `grok-imagine-video`, not `grok-imagine-video-1.5`, which is generation-only.)
+- **`onMediaProgress` hook.** Long-running async video ops (generate/extend/edit) now emit an
+  `onMediaProgress` event once per poll (`{ type, provider, operationId, progress, model }`), so a UI can
+  render a progress bar. Progress values confirmed live (0→100).
+- **`RawMediaResult.sourceUrl` + `MediaMeta.sourceUrl`.** Async video results now carry the provider's
+  hosted URL, so callers can render or re-submit the asset without holding the bytes.
+- **Unified reasoning visibility.** `ThinkingConfig` gains `visibility: 'full' (default) | 'summary' |
+  'hidden'`, mapping to Anthropic `enabled.display`, OpenAI Responses `summary`, and Google
+  `includeThoughts` — one knob for "how much reasoning comes back" across providers (best-effort; a
+  provider without a middle state degrades `summary` to full). Default `full` = prior behaviour.
+- **OpenAI reasoning execution mode.** `providerOptions.reasoningMode: 'standard' | 'pro'` maps to
+  `reasoning.mode` on the OpenAI **Responses** path (chat-completions rejects it). Kept in
+  `providerOptions` rather than a first-class knob since only one provider/API honours it.
+- **Google `translationConfig` passthrough.** `providerOptions.translationConfig` forwards to
+  `generationConfig.translationConfig` on generateContent (Gemini Developer API; live-verified 200).
+- **OpenAI native moderation blocking.** `providerOptions.moderationPolicy`
+  (`{ input?: { mode: 'score'|'block' }, output?: {…} }`) forwards to OpenAI's `moderation.policy` on
+  Responses + chat for server-side blocking. Unified moderation stays report-only by design (blocking is
+  `moderationGuardrail` at the agent layer); this is an OpenAI-specific opt-in, so it lives in
+  `providerOptions`. Live-verified the field is accepted.
+- **OpenAI explicit prompt caching.** `providerOptions.promptCacheOptions`
+  (`{ mode: 'implicit'|'explicit', ttl: '30m' }`) forwards to `prompt_cache_options` (gpt-5.6+),
+  true-OpenAI only (xai/openrouter inherit the builder and don't emit it). Note: OpenAI caches
+  **implicitly by default**, so the unified `cache` config already works there with no config — this
+  passthrough is for manual control. (`prompt_cache_retention` is deprecated upstream in favour of
+  `prompt_cache_options.ttl`.)
+- **OpenAI programmatic tool calling (Responses).** `BuiltinTool` gains `programmatic_tool_calling`, and
+  `FunctionTool` gains `allowedCallers?: ('direct'|'programmatic')[]` + `outputSchema?` — emitted on the
+  OpenAI Responses path only. Live-verified on gpt-5.6 (tool calls succeed; older models reject the
+  builtin, which is model-gated). (Surfacing the `program`/`program_output` output items is deferred; the
+  parser already tolerates them without error.)
+
+### Fixed
+- **OpenAI prompt-cache write tokens were dropped.** Both usage parsers hardcoded `cacheWriteTokens: 0`;
+  they now read `input_tokens_details.cache_write_tokens` (Responses) / `prompt_tokens_details.
+  cache_write_tokens` (chat), so cost accounting no longer under-reports explicit prompt caching.
+- **Google reasoning was live-broken (two paths).** generateContent sent `thinkingLevel`, which the
+  Gemini Developer API 400s on **2.5** models (it is 3.x-only) — now routed per series: 2.5 →
+  `thinkingBudget` (token count), 3.x → `thinkingLevel`. The Interactions path wrapped `thinking_config`
+  (rejected outright) and used uppercase values — it takes `thinking_level` **flat** on `generation_config`
+  and **lowercase** (`minimal/low/medium/high`). Both live-verified across gemini-2.5 + 3.5.
+- **Google Interactions rejected sampling penalties.** We emitted `presence_penalty`/`frequency_penalty`
+  on the Interactions path, which the API 400s ("Unknown parameter") — upstream removed them from its
+  Interactions config. No longer emitted there (still valid on generateContent).
+- **Streamed tool-call id collision on OpenAI-compatible backends.** The chat-completions stream parser
+  keyed tool-call fragments by `id ?? ''`, so parallel calls from backends that omit ids (LiteLLM/Bedrock,
+  some OpenRouter routes) merged into one. Fragments are now correlated by `index`, with a stable
+  `call_<uuid>` synthesized once per index when the backend omits ids.
+- **`content_filter` finish reason was flattened to `stop`/`length`.** The chat-completions stream reason
+  map lacked `content_filter`, `AgentLoop` derived every normal-completion finish as `stop`, and the
+  Responses parser mapped `status: 'incomplete'` to `length` regardless of `incomplete_details.reason` —
+  all discarding the provider's actual reason. Now the stream map, the loop, and the Responses parser
+  (reading `incomplete_details.reason`) all surface `content_filter` (and `length`) to consumers — so a
+  moderation/safety block is distinguishable from a token cap. (Our loop already terminates on non-tool
+  finishes, so it never retry-looped on an empty filtered turn.)
+- **Browser: xAI video result was unusable (CORS).** The generated clip lives on a cross-origin bucket
+  (`vidgen.x.ai`) that sends no `Access-Control-Allow-Origin`, so `downloadVideo`'s programmatic
+  byte-fetch was blocked in the browser and video generation failed outright. In the browser the adapter
+  now returns the hosted URL (via `sourceUrl`) with empty bytes instead of fetching — `<video src>` plays
+  it cross-origin without CORS, and it can be re-submitted as a `sourceVideo`. Node/Bun still download the
+  bytes. (Node-only tests couldn't surface this; CORS isn't enforced off-browser.)
+- **Google `editImage` aspect ratio / size (same bug, second code path).** The 1.6.1 fix moved
+  `aspectRatio` / `imageSize` to `generationConfig.imageConfig` only in `generateImage`; the sibling
+  `editImage` method still wrote `generationConfig.responseFormat.image` and so 400'd on any edit that
+  passed an aspect ratio or size. Now both image paths use `imageConfig`. Verified live end-to-end:
+  generate → edit round-trip both return an image at `16:9` / `2K`. Locked with a unit regression on the
+  `editImage` request body.
+- **xAI video generation polled forever after the job finished.** `getVideoStatus` only treated
+  `status: "completed"`/`"ready"` (or a `download_url`) as done, but xAI reports terminal success as
+  `status: "done"` with the URL under `video.url` — so a finished job kept polling until the wait cap and
+  never returned. `downloadVideo` likewise read `download_url`/`url` and missed `video.url` (and duration
+  under `video.duration`). Both now read the real `video.*` shape (flat fallbacks kept), and terminal
+  `status: "done"`/`"expired"` are handled. Progress is now carried on the processing status. Verified
+  live end-to-end (grok-imagine-video-1.5 image-to-video: progress 0→75→100 → downloaded 2.5 MB); locked
+  with a unit test replaying the real server payload.
 
 ## [1.6.1] - 2026-07-13
 

package/MIGRATION.md

@@ -0,0 +1,93 @@
+# Migrating to 2.0.0
+
+**Most codebases need no source changes.** The point of this library is that provider churn is our
+problem to absorb, not yours — and a whole cycle of it (a new MCP protocol revision, a new OpenAI
+major, four SDK majors) landed here without becoming a breaking change for you.
+
+Three things can require action, and none of them is a provider change.
+
+## 1. Node 22+ is required
+
+```json
+"engines": { "node": ">=22", "bun": ">=1.1.0" }
+```
+
+Node 18 and 20 are both end-of-life. 22 is also the floor `openai-node` 7 adopted.
+
+**What to do:** upgrade the runtime. Nothing in your code changes.
+
+## 2. `tiktoken` is now an optional PEER dependency
+
+It used to be an `optionalDependency`, which means *"do not fail the install if this package fails
+to build"* — npm installed it **anyway**. Every consumer received its ~5.6 MB wasm file, and
+bundlers emitted it into production builds even when local token counting was never used. One
+consumer measured it at **88% of their shipped output**.
+
+**What to do:** if you use exact local OpenAI token counting, install it yourself:
+
+```sh
+npm install tiktoken
+```
+
+If you don't, do nothing — you now stop paying for a feature you never asked for. Token counting
+still works without it: `countTokens` falls back to the provider count-API (Anthropic/Google) or a
+calibrated heuristic. The error thrown when the package is genuinely needed names it and the
+alternatives.
+
+It still works in the **browser** when you do install it; it is deliberately not stubbed out.
+
+## 3. Two unions are now open — add a `default` branch
+
+`FinishReason` and `ContentPart` gained members and are now open unions
+(`KnownFinishReason | (string & {})`). If you `switch` over either **exhaustively, with no
+`default`**, TypeScript will now complain.
+
+```ts
+switch (res.finishReason) {
+  case 'stop': …
+  case 'tool_use': …
+  default: …   // <- add this
+}
+```
+
+**This is deliberate, and it is the reason most of this release is not breaking.** Providers grew
+four new terminal statuses in a single cycle. With a closed union, every one of those is a breaking
+change for *every* consumer — including consumers of providers that changed nothing. Open unions
+convert that into an additive change, at the cost of one `default` branch written once
+(CONSTITUTION.md R1).
+
+New members you can now handle if you want them: `'pending'` (queued / in-progress — previously
+flattened to `'stop'`, claiming a clean finish for a response that had not run), and
+`'malformed_tool_call'`. `ContentPart` gained `program_call` / `program_result`.
+
+## 4. One changed signature
+
+`OpenAITranscriptionAdapter.transcribe()` returns `OpenAITranscriptionResult` instead of `string`:
+
+```ts
+// before
+const text = await adapter.transcribe(req, fetch);
+
+// after
+const { text } = await adapter.transcribe(req, fetch);
+```
+
+The result also carries optional `segments`, `words`, `languages` and `durationSeconds`.
+
+**The `transcribe()` helper is unaffected** — it already returned an object, and `text` is still
+required on it. Only the low-level adapter class changed.
+
+## What did NOT break
+
+Worth stating, because it is the whole design goal:
+
+- **MCP 2025-11-25 keeps working, untouched.** The 2026-07-28 revision deletes the `initialize`
+  handshake, the session id and the entire back-channel — but this client speaks **both** wires and
+  prefers neither. No legacy path was removed. Even the WebSocket transport stays, documented as
+  non-standard, though upstream deleted theirs.
+- **Every response type only gained optional fields.** Nothing was removed, narrowed, or made
+  required.
+- **Every request option is still accepted.** Where a provider stopped taking one, we decide
+  internally whether it reaches the wire — your build does not break because of their typings.
+
+Full detail in [CHANGELOG.md](./CHANGELOG.md).