@combycode/llm-sdk 3.0.0 → 3.2.1

package/CHANGELOG.md

@@ -4,6 +4,156 @@ 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.2.1] — 2026-08-31
+
+### Fixed
+
+- **Three TypeScript errors in an MCP test file** that made v3.2.0 unpublishable: `searchParams.get()`
+  returns `string | null` while `.at(-1)` returns `string | undefined`, and `toBe` has no overload
+  spanning both. The assertions are unchanged; only their types are aligned.
+
+- **Two lint warnings** left standing in `network/engine.ts` (an unused type import) and an MCP test
+  helper (`let x!` forward declarations that nothing forward-references).
+
+### Internal
+
+- **The release gate now runs lint, typecheck and the tests** (`G1 build-green` in CombyCode's shared
+  quality-gate). v3.2.0 was tagged with a green gate and a red typecheck, because the gate checked
+  documentation and consumers while lint and typecheck lived in a playbook sentence — the half a
+  human has to remember. The gate's own README names that failure mode: "a checklist you have to
+  remember to read is guarded by the same attention that failed in the first place." The check ships
+  with the good/bad/blind fixtures the selftest requires, and was verified against the exact error
+  that escaped.
+
+## [3.2.0] — 2026-08-31
+
+### Added
+
+- **`response.citations` — the sources an answer cited, unified across providers.** Reaching them
+  meant regexing `response.raw`; the SDK's own web-search example did exactly that, which is every
+  consumer reimplementing provider knowledge that belongs here. Four wire shapes are read: Anthropic's
+  text-block `citations[]` (the only provider that also reports the cited passage), Google's
+  `groundingMetadata.groundingChunks[]`, OpenAI Responses/Chat `url_citation` annotations, and xAI's
+  bare top-level `citations[]`.
+
+  Distinct from `builtinToolCalls`, which records what the model *invoked*: a turn can run three
+  searches and cite one page. Through an agent run the sources **accumulate across steps**, deduped
+  by URL — a run that searches in step 1 and answers in step 3 keeps the sources its answer rests on.
+  Optional per R3 (`response.citations ?? []`); absent on `stream()`, which holds no raw payload, and
+  on Google's Interactions surface, whose grounding shape has not been measured.
+
+  **Streaming reports them too**, as a `citation` StreamEvent per source, collected onto the streamed
+  final response so `stream()` and `complete()` agree. Four more measured shapes, since a stream never
+  assembles the body the buffered reader parses: Anthropic `citations_delta`, Responses
+  `response.output_text.annotation.added` (OpenAI and xAI), chat-completions `delta.annotations`, and
+  Google's *late* populated `groundingMetadata` chunk — the first one carrying that key is empty, so
+  latching on first sight would report a search and no sources.
+
+  Verified live on Anthropic, OpenAI, Google, xAI and OpenRouter, buffered and streamed: 5/5 providers
+  return real cited URLs for the web-search scenario, which previously reported `no-citation` on all
+  five. Note Google reports each source as a `grounding-api-redirect` URL, not the page itself.
+
+### Fixed
+
+- **xAI file `delete`, `getInfo` and `list` never worked.** `XAIFileAdapter` is exported, and three
+  of its four methods rejected with `unknown spec: xai/files.<op>` before any HTTP — only
+  `xai/files.upload` had ever been written, so roughly twenty lines of response mapping below them
+  had never run. The three specs follow `xai.upload`'s own note that the surface differs from
+  OpenAI's only in the upload `purpose`, so they carry the same paths and the same Bearer base.
+
+- **`listModelsLive` was blocked by CORS in the browser, for Anthropic only.** Anthropic refuses a
+  browser request without an explicit opt-in header. The chat path sends it and the Anthropic files
+  specs carry it, but `models.list` lost it when that request moved to a spec: the header had lived
+  in the helper's own table, which nothing called any more. Measured from a browser with a raw
+  fetch — `/v1/models` returns 200 with the header and fails without it. The sandbox listed models
+  through `Promise.allSettled` and kept only the fulfilled results, so the rejection was swallowed
+  and Anthropic simply showed no models rather than an error.
+
+### Removed
+
+- **Five private functions left behind by the spec migration.** Each was live until its area moved to
+  the spec-driven builder, which renamed it with a leading underscore instead of deleting it:
+  `_buildForm`, `_batchName`, `_toOpenAIAudioFormat`, `_toResponseModalities` and
+  `LiveSpec.headers`. Each was checked field by field against the spec that replaced it before
+  removal — and the last of them was **not** equivalent, which is how the CORS bug above was found.
+
+### Internal
+
+- **Line coverage 91.62% → 99.53%**, function coverage 87.53% → 97.41%, across 2290 → 4051 tests.
+  Eleven modules had no function coverage at all — `batcher.ts` ran 3.5% of its lines,
+  `plugins/internal-tools/runner/runner.ts` 3.7%, `transport-ws.ts` 9.6%. Every new test is mutation-verified: the
+  source line it claims to cover was broken and the test watched to fail.
+
+  The exercise found ten defects no existing test caught, each pinned as a `DEFECT:` test rather
+  than fixed in the same pass: `ResponseStore.list(null)` returning every user's response ids,
+  `chunker.ts` silently dropping space-free text (3000 characters of CJK or base64 yield one
+  400-character chunk), `attachment.ts fromBlob` leaving the MIME type empty because a type-less
+  `Blob` reports `''` rather than `null`, and `oauth.ts tryRefresh` discarding the refresh token it
+  means to preserve.
+
+  Two pre-existing tests turned out to execute no code at all — one asserts against `readFileSync`
+  of `realtime.ts` with regexes over the source text, which is why that file sat at 0% functions
+  while appearing tested.
+
+- **A coverage floor that can actually fail.** `bunfig.toml`'s `coverageThreshold` is accepted and
+  ignored by bun 1.3.14 — set to an impossible 1.0 the run still exits 0 — so the floor is its own
+  step (`bun run coverage:gate`), carrying a `--self-test` that proves it discriminates.
+
+
+## [3.1.0] — 2026-08-25
+
+### Added
+
+- **A provider can declare a hosted tool it will not run beside certain content** (`toolConstraints`
+  in a wire spec, plus a `hasPartType` condition). Measured 2026-08-25: Google answers 400 `The mime
+  type: video/mp4 is not supported for code execution` when `code_interpreter` accompanies a PDF or a
+  video. Images are fine, `web_search` is fine, and OpenAI accepts every combination — so it is one
+  provider's rule, and it lives in that provider's spec as data rather than as an `if` in the builder.
+
+  A matched constraint drops the tool — `hasTool` reports it absent, so the spec's existing guard
+  omits it with no further edit — and records why on the built request. `LLMClient` emits each as
+  `onWarning` with code `request_adjusted`, on both `complete()` and `stream()`. Dropping it quietly
+  would trade a confusing error for the silent loss of a capability the caller asked for.
+
+- **Any spelling of a model id finds the model, and every helper resolves it the same way.**
+  Providers spell one version several ways and users copy whichever they saw: `gpt-4.1` / `gpt-4-1`,
+  `gemini-2.5-flash` / `gemini-2-5-flash`, `claude-haiku-4.5` / `claude-haiku-4-5`. Only some are
+  callable, and the rest missed the catalog outright — no price, no capabilities — and were then
+  forwarded to the provider verbatim, turning a spelling difference into a 404.
+
+  Catalog lookups are now insensitive to the separator between two digits and to case, so ~556
+  previously-unresolvable spellings reach their entry. The rule is deliberately narrow — only a
+  separator between two DIGITS moves — and is verified across the shipped catalogs to merge nothing:
+  1016 normalized keys, zero collisions.
+
+  `resolveModelId()` now always returns something callable. A spelling the provider itself accepts is
+  sent unchanged; one it would reject is corrected to the canonical id instead of being forwarded;
+  an unknown id still passes through verbatim, so fine-tunes and same-day releases keep working.
+
+### Fixed
+
+- **`createRealtime()` never translated the model id.** It parsed the provider but skipped the
+  catalog step every other helper performs, so a realtime session was the one path that sent our
+  slug instead of the provider's id. All helpers now share the single resolution step, and a test
+  calls each one and reads the wire so a helper that forgets fails CI rather than a user's request.
+
+- **An Anthropic model is reachable by the name Anthropic documents.** `claude-haiku-4-5` — the
+  spelling in Anthropic's own docs, and one the API accepts — matched no catalog key and no alias,
+  because `/v1/models` lists only the dated snapshot (`claude-haiku-4-5-20251001`) while our slug
+  dots the version (`claude-haiku-4.5`). `get()` and `getPricing()` missed in silence, and an
+  unpriced model is indistinguishable from a free one: reported from production as 72k tokens
+  billed at $0.00.
+
+  The undated form is now carried as an alias for the four affected entries (`claude-haiku-4-5`,
+  `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-opus-4-1`), derived in the catalog pipeline so a
+  regeneration keeps it. Anthropic-only, and deliberately so — the same date-stripping applied to
+  other providers invents ids that do not exist (`imagen-4.0-generate`, `command-r7b-12`), since
+  only there is the undated form a truncation rather than a real alias. Each was probed live.
+
+  `providerModelName` is untouched, so **what goes on the wire is unchanged**: a slug still
+  translates to its pinned snapshot, and an alias is still sent verbatim as the floating id the
+  caller chose. This widens what the catalog recognises, never what it calls.
+
 ## [3.0.0] — 2026-08-24
 
 ### Added

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

@@ -1,7 +1,7 @@
 /** Mutable accumulator for a single agent loop step.
  *  Passed through stream-event helpers so they don't fight closure state. */
 import type { ToolCallPart } from '../llm/types/messages';
-import type { Usage } from '../llm/types/response';
+import type { Citation, Usage } from '../llm/types/response';
 /** Accumulation bucket for one in-progress tool call (before tool_call_end). */
 export interface ToolCallAccumEntry {
     id: string;
@@ -19,4 +19,8 @@ export interface StepState {
     toolCallAccum: Map<string, ToolCallAccumEntry>;
     stepUsage: Usage;
     stepFinishReason: string;
+    /** Sources cited during this step, keyed by url. A Map rather than an array
+     *  because Google repeats its grounding chunks across late chunks, and one page
+     *  cited twice is one source. */
+    stepCitations: Map<string, Citation>;
 }

package/dist/catalog/catalog.d.ts

@@ -141,14 +141,26 @@ export declare class ModelCatalog {
     /** `provider/alias` → `provider/canonical-slug`. Lets get()/resolveModelId
      *  accept any callable id (providerModelName, dated snapshot) AND the slug. */
     private aliasIndex;
+    /** `provider/normalized-id` → `provider/canonical-slug`. The last resort, so a
+     *  user's spelling of a version never decides whether the model is found. */
+    private normIndex;
     private key;
+    private normKey;
     set(provider: string, model: string, info: Partial<Omit<ModelInfo, 'provider' | 'model'>> & {
         pricing: ModelPricing;
     }): void;
     get(provider: string, model: string): ModelInfo | null;
-    /** The exact id to SEND to the provider for a given model string. Translates
-     *  our slug → providerModelName; passes an already-callable id (alias) through
-     *  verbatim (respects an explicit choice); unknown model → verbatim passthrough. */
+    /** The exact id to SEND to the provider for a given model string.
+     *
+     *  Three cases, and the difference between them is what the caller ASKED for:
+     *    - our slug            → translate to providerModelName (the pinned snapshot)
+     *    - an id the provider itself accepts (a listed alias, e.g. a dated snapshot
+     *      or anthropic's undated name) → verbatim, because it is a deliberate choice
+     *      and rewriting it would pin a caller who asked to float
+     *    - a spelling variant that is NOT callable (`gemini-2-5-flash`) → the
+     *      canonical entry's providerModelName, since forwarding it verbatim only
+     *      produces a 404 with the user's typo in it
+     *    - unknown → verbatim, so a model we have never heard of still works */
     resolveModelId(provider: string, model: string): string;
     getPricing(provider: string, model: string): ModelPricing | null;
     getPreferredApi(provider: string, model: string): ApiType | null;

package/dist/helpers/select-model.d.ts

@@ -34,6 +34,41 @@ declare const DEFAULT_THRESHOLDS: {
     'context.small': number;
     'context.large': number;
 };
+/** One filter a UI can offer, and what it accepts. */
+export interface FilterFacet {
+    /** The DSL key, e.g. `price`. Write it as `key:value`. */
+    key: string;
+    /** Group heading for a picker. */
+    category: 'what it is' | 'cost' | 'thinking' | 'inputs' | 'hosted tools' | 'availability';
+    /** Short human label. */
+    label: string;
+    /** The values this key accepts. Empty when the key is a bare flag (`vision`),
+     *  which the parser reads as `key:yes`. */
+    values: string[];
+    /** True when the key also accepts `> N` / `< N`, so a picker can offer a number. */
+    numeric: boolean;
+    /** True when a bare `key` (no value) is meaningful — the parser expands it to
+     *  `key:yes`. */
+    bare: boolean;
+}
+/** Every clause the query parser understands, as data.
+ *
+ *  Exported because the alternative is a UI hand-listing the same tags: a second
+ *  copy of this vocabulary, drifting from the parser the first time either moves,
+ *  and drifting invisibly because a wrong tag reads as "no models matched" rather
+ *  than as an error. Here the picker and the parser cannot disagree — both come
+ *  from `KNOWN_KEYS`, `CAP_KEYS` and `BUILTIN_TOOL_KEYS` above.
+ *
+ *  `type`, `provider`, `status` and `tier` take their values from the CATALOG
+ *  when one is passed, because those are open sets: a provider ships a new model
+ *  type and a hard-coded list is wrong that day. Without a catalog they come back
+ *  empty rather than guessed — an empty list is honest, a stale list is not. */
+export declare function filterFacets(catalog?: {
+    list(): ModelInfo[];
+}): FilterFacet[];
+/** The shorthand tags the parser expands before matching (`cheap` → `price:low`).
+ *  A picker can show these as one-click presets. */
+export declare function filterAliases(): Record<string, string>;
 /** All matching models, ranked cheapest-first (tiebreak: newest version). */
 export declare function selectModels(query: string | string[], opts?: SelectOptions): ModelInfo[];
 /** The single best match as a `provider/slug` string (feedable to complete), or null. */