@combycode/llm-sdk 1.7.0 → 2.0.1

package/CHANGELOG.md

@@ -4,7 +4,468 @@ 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.1] - 2026-08-10
+
+Three defects reported by a consumer within a day of 2.0.0 — all reachable by reading the shipped
+`.d.ts`, none caught by our gate. See the note at the end.
+
+### Fixed
+
+- **`agent.stream()` now carries `phase` on text events.** The raw stream event had it, and the
+  agent mapper *used* it internally to keep commentary out of the answer — then yielded both deltas
+  through one `{ type: 'text', text }` with the phase stripped. A UI streaming those straight
+  through put the model's thinking-aloud into the transcript **as if it were the reply**, with no
+  way to tell them apart. `finalAnswerText()` could not help: it takes a finished message's
+  `content`, not deltas.
+  - Additive: `phase` is **absent** (not `undefined`) when the provider reports none, so every
+    non-codex provider is byte-identical to before.
+- **Docs: `agent.run()` does not exist.** The agent-loop guide recommended it for a non-throwing
+  report. The class exposes `stop` / `complete` / `structuredComplete` / `stream`; the report is
+  reached with `try/catch` + `agent.lastReport`. The guide now shows that.
+- **Docs: the 2.0.0 changelog overstated live commentary.** It said commentary "is still yielded to
+  the consumer (a UI may well want to render it live)" — true only in the sense that the bytes
+  arrived; they were unlabelled, so a UI could not act on them. The 2.0.0 entry now says so and
+  points here.
+
+### Why this got out
+
+The feature was verified end-to-end on the **buffered** path (`finalAnswerText`, `response.text`,
+live-tested against real models) and never once from the **layer most consumers actually call**.
+1778 tests, four MCP transports and two live corpora, and no check that a shipped type was usable
+from `agent.stream()`. The gate was deep where it was pointed and blind where it was not — so the
+release checklist now includes a consumer-surface pass over the published `.d.ts`.
+
+## [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 yielded to the consumer and preserved in the
+    assembled content as its own phase-tagged part. (In 2.0.0 the agent-layer event dropped the
+    phase, so a UI could not act on it — corrected in 2.0.1.)
+  - 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
 

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).

package/README.md

@@ -10,7 +10,7 @@ A unified, pluggable AI SDK for accessing the LLMs of every major provider —
   `model:tier` selectors, capability-based `select()`, tiered pricing, and cost
   tracking.
 - **Cross-environment.** The same code runs on Node, Bun, and the browser. Zero
-  runtime dependencies, ESM.
+  **required** runtime dependencies, ESM.
 
 ## Install
 
@@ -18,7 +18,22 @@ A unified, pluggable AI SDK for accessing the LLMs of every major provider —
 npm install @combycode/llm-sdk      # or: bun add @combycode/llm-sdk
 ```
 
-Requires Node ≥ 18 or Bun ≥ 1.1.
+Upgrading from 1.x? See [MIGRATION.md](./MIGRATION.md) — three things can
+require action, and none of them is a provider change.
+
+Requires **Node ≥ 22** or Bun ≥ 1.1. (Node 18 and 20 are end-of-life; 22 is also the floor
+`openai-node` 7 adopted.)
+
+`dependencies` is empty. The one optional extra is `tiktoken`, an **optional peer** for exact local
+OpenAI token counting — install it only if you want that:
+
+```sh
+npm install tiktoken
+```
+
+Without it everything still works: token counting falls back to the provider count-API
+(Anthropic/Google) or a calibrated heuristic. It is a peer rather than an `optionalDependency` so
+its ~5.6 MB wasm is not installed — or bundled — for people who never use it.
 
 ## Quickstart
 

package/dist/agent/loop-config.d.ts

@@ -4,6 +4,7 @@ import type { LLMClient } from '../llm/client';
 import type { CacheConfig, ThinkingConfig } from '../llm/types/request';
 import type { ConversationHistory } from './history';
 import type { HistorySnapshot } from './history-types';
+import type { ReflectAndRetryConfig } from './reflect-retry';
 import type { AgentTool } from './types';
 import type { Guardrail, ToolInputGuardrail } from './guardrail-types';
 import type { PermissionPolicy } from '../plugins/permissions/policy';
@@ -23,6 +24,27 @@ export interface AgentLoopConfig {
     context?: string;
     /** Executable tools. Indexed by function name (FunctionTool) or type (BuiltinTool). */
     tools?: AgentTool[];
+    /** What to do when two tools claim the same registry key.
+     *
+     *  Registration is a map keyed by function name / builtin type, so a collision means one tool
+     *  SILENTLY replaces another and the model never sees it. The failure then surfaces much later
+     *  as "the model called the wrong tool", with nothing in the logs pointing at the cause.
+     *
+     *  - `'warn'` (default) — keep last-write-wins, but emit an `onWarning`
+     *    (`code: 'tool_name_collision'`) naming the key and which tool lost.
+     *  - `'error'` — throw at construction / `addTool()`, before the model is ever called.
+     *
+     *  Defaults to `'warn'` so an app that unknowingly has a collision keeps working
+     *  (CONSTITUTION.md R4) — the collision just stops being invisible. */
+    toolNameCollisionPolicy?: 'warn' | 'error';
+    /** Self-healing recovery from a recoverable MODEL failure (a malformed tool call, a hallucinated
+     *  tool name, a truncated call). The model is given structured guidance naming the attempt and
+     *  told not to repeat the same call, then the step is retried within a bounded budget.
+     *
+     *  Off unless configured: a retry costs a real request, so it is the caller's decision. This is
+     *  NOT a network retry — the engine already handles transport failures. This one is for a request
+     *  that succeeded and came back unusable, which resending unchanged would never fix. */
+    reflectAndRetry?: ReflectAndRetryConfig;
     /** Reuse an existing history (or rehydrate from a snapshot). New history
      *  is created when omitted. */
     history?: ConversationHistory | HistorySnapshot;

package/dist/agent/loop-step-state.d.ts

@@ -12,6 +12,8 @@ export interface ToolCallAccumEntry {
 /** All mutable state for one streaming step inside AgentLoop.stream(). */
 export interface StepState {
     stepText: string;
+    /** Commentary deltas, kept apart from stepText so the step's answer excludes narration. */
+    stepCommentary: string;
     stepThinking: string;
     stepToolCalls: ToolCallPart[];
     toolCallAccum: Map<string, ToolCallAccumEntry>;