@combycode/llm-sdk 2.2.2 → 2.3.0

package/CHANGELOG.md

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

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

@@ -20,6 +20,10 @@ export type RunTrace = TraceContext & {
     sessionId: string;
     requestId: string;
 };
+/** Why a run ended. Written inline in both `complete()` and `stream()` and in
+ *  `finalizeRun`'s argument list, which is three places to keep in step; named
+ *  so adding a reason is one edit. */
+export type RunEndReason = 'done' | 'stopped' | 'error' | 'guardrail' | 'max_steps';
 /** Create a fresh StepState for the start of a streaming step. */
 export declare function makeStepState(): StepState;
 /** Accumulate one SSE StreamEvent into StepState.

package/dist/agent/loop.d.ts

@@ -94,6 +94,41 @@ export declare class AgentLoop {
     removeTool(name: string): void;
     toolNames(): string[];
     stop(): void;
+    /** Record a thrown error onto the run: emit `onRunError` and return the parts
+     *  the caller assigns. Both paths report `phase: 'llm_call'`. */
+    private recordRunError;
+    /** The run's final text.
+     *
+     *  `finalAnswerText` strips `phase: 'commentary'` parts: a codex-family model
+     *  narrates before it answers and `response.text` concatenates both, so an
+     *  agent's final output used to include its own thinking-out-loud. Falls back
+     *  to `.text` when the content carries no text parts, and is identical to
+     *  `.text` for every model that reports no phase.
+     *
+     *  The streaming path passes what it accumulated; the non-streaming path lets
+     *  the last response decide. Both share the guardrail / max-steps overrides. */
+    private resolveFinalText;
+    /** Compose the run's CompletionResponse. `media` and `raw` are parameters
+     *  because the two paths genuinely differ: the streaming path has already
+     *  emitted media as events and never holds a raw provider payload. */
+    private buildFinalResponse;
+    /** Close out a run: write the report, then surface a failure.
+     *
+     *  The order matters and is the reason this is one function rather than two
+     *  calls at each site — a failed run must still emit its metrics and hooks
+     *  before the error propagates, or a crash silently loses the run's telemetry.
+     *  A failed run throws rather than returning empty text, matching the raw
+     *  client. */
+    private settleRun;
+    /** Per-step options for the underlying LLM call: loop defaults, then the
+     *  caller's overrides, then the run's trace.
+     *
+     *  `complete()` and `stream()` duplicated this verbatim, differing only in the
+     *  name of the local holding the composed system prompt. That is a bad place
+     *  for a copy: the ctx block below is what stops one conversation arriving at
+     *  the collector as several unrelated traces, and a fix applied to one path
+     *  would have left the other silently splitting. */
+    private buildStepOptions;
     complete(input: string | ContentPart[] | Message[], options?: ExecuteOptions): Promise<CompletionResponse>;
     /** Run `complete` with a JSON Schema enforced via `structured`, then
      *  JSON.parse the response text. Tool calls are still allowed within the

package/dist/{llm/providers → catalog}/builtin-tools.d.ts

@@ -14,5 +14,5 @@
  *    - web_fetch        → anthropic (web_fetch_20260318), google (urlContext).
  *      OpenAI has no separate fetch tool (its web_search does page-open); xAI /
  *      openrouter expose none. */
-import type { ProviderName } from '../types/provider';
+import type { ProviderName } from '../llm/types/provider';
 export declare const PROVIDER_BUILTIN_TOOLS: Record<ProviderName, readonly string[]>;

package/dist/{plugins/model-catalog → catalog}/catalog.d.ts

@@ -73,6 +73,27 @@ export interface TokenizerInfo {
     countApiAvailable: boolean;
     tiktokenEncoding?: string;
 }
+/** Per-model WIRE traits: how to say a thing to this model, as opposed to
+ *  `capabilities` / `reasoning`, which say what the model can do.
+ *
+ *  This is the gap that produced two shipped bugs. The catalog knew a model
+ *  supported reasoning; nothing knew which of two incompatible `thinking` shapes
+ *  it accepted, so adapters parsed the model id with regexes and got it wrong
+ *  twice (2.2.1, and the 4.0 date-suffix defect fixed in 039 A1).
+ *
+ *  Adapters read these through `NormalizedRequest.wire`, which `LLMClient`
+ *  resolves from the catalog. When the catalog has no entry the adapters fall
+ *  back to parsing the id, so a catalog-less engine still works — the fallback
+ *  is what a future release removes once every model is pinned. */
+export interface ModelWire {
+    /** Which `thinking` shape the wire accepts.
+     *  Anthropic: `adaptive` (4.6+) vs `budgeted` (pre-4.6, needs budget_tokens).
+     *  Google: `level` (3.x, thinkingLevel enum) vs `budget` (2.5, token count). */
+    thinking?: 'adaptive' | 'budgeted' | 'budget' | 'level';
+    /** Whether the model accepts a top-k sampling parameter. Anthropic retired it
+     *  after Opus 4.6 and 400s on models that no longer take it. */
+    topK?: boolean;
+}
 export interface ModelInfo {
     provider: string;
     /** Catalog key — our canonical (normalised) slug, e.g. `claude-opus-4.8`. */
@@ -94,6 +115,19 @@ export interface ModelInfo {
     /** Other callable ids that resolve to this model (dated snapshots, the bare
      *  callable form). Indexed for lookup + accepted as model strings. */
     aliases?: string[];
+    /** Per-model wire traits — see ModelWire. */
+    wire?: ModelWire;
+    /** Which wire spec builds this model's requests, e.g. `anthropic/messages@4.7`.
+     *
+     *  The specs live in `src/wire/specs` and are the artifact the Python and Rust
+     *  ports consume, so the pin is what lets all three agree on a model without
+     *  each re-deriving it from the model id.
+     *
+     *  Today the pin is carried and validated but the hand-written adapters still
+     *  build requests, reading `wire` above. Driving them from the pinned spec is
+     *  the 3.0.0 step, at which point `wire` goes away — the spec already encodes
+     *  the same knowledge, which is why a test asserts the two agree. */
+    wireSpec?: string;
     /** Model role/modality: chat | code | image | video | tts | stt | embedding | … */
     type?: string;
     /** Content kinds the model ACCEPTS as input: text | image | audio | video |

package/dist/helpers/client-pool.d.ts

@@ -3,7 +3,7 @@
  *  ClientResolver and (in the legacy SDK) by InternalToolRunner. */
 import { LLMClient } from '../llm/client';
 import type { LLMClientConfig } from '../llm/client-config';
-import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { ModelCatalog } from '../catalog/catalog';
 export declare class ClientPool {
     private readonly catalog?;
     private clients;

package/dist/helpers/client-resolver.d.ts

@@ -9,7 +9,7 @@ import type { LLMClientConfig } from '../llm/client-config';
 import type { HookBus } from '../bus/hook-bus';
 import type { ProviderName } from '../llm/types/provider';
 import type { ServiceTier } from '../llm/types/tiers';
-import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { ModelCatalog } from '../catalog/catalog';
 import type { EngineFetch, EngineFetchStream } from '../network/types';
 export interface ClientResolverConfig {
     /** provider → API key. Providers absent from this map can't be resolved. */

package/dist/helpers/engine.d.ts

@@ -17,13 +17,15 @@
  *    // llm.client uses engine.fetch + engine.hooks automatically. */
 import { AgentBus } from '../bus/agent-bus';
 import { HookBus } from '../bus/hook-bus';
+import type { LLMClient } from '../llm/client';
+import { type CreateLLMOptions } from './llm';
 import type { ProviderName } from '../llm/types/provider';
 import { NetworkEngine, type QueueSettings } from '../network/engine';
 import type { RetryPolicyOverride } from '../network/queue-state-config';
 import type { EngineConnect, EngineFetch, EngineFetchStream, FetchFn } from '../network/types';
 import { Cache } from '../plugins/cache/cache';
 import { CostCollector } from '../plugins/cost-collector/collector';
-import { ModelCatalog } from '../plugins/model-catalog/catalog';
+import { ModelCatalog } from '../catalog/catalog';
 import { TelemetryAdapter, type TelemetryAdapterOptions } from '../plugins/telemetry/telemetry';
 import type { Persistence } from '../plugins/persistence/types';
 export interface EngineHandle {
@@ -63,6 +65,15 @@ export interface EngineHandle {
      *  createMediaOutput, complete) read these to wire LLM clients without
      *  the caller passing apiKey explicitly. */
     apiKeys: Partial<Record<ProviderName, string>>;
+    /** Build an LLMClient bound to this engine.
+     *
+     *  Exists so lower layers can obtain a client without importing the helpers
+     *  layer: `plugins/internal-tools` needs one for LLM-backed tools, and
+     *  importing `createLLM` directly made `plugins` depend on `helpers` while
+     *  `helpers` already depended on `plugins` — a cycle that a Rust crate split
+     *  cannot express. The engine is something those plugins already hold, so it
+     *  is the natural place to hand the capability down. */
+    createClient(options: Omit<CreateLLMOptions, 'engine'>): LLMClient;
     /** Tear down all owned plugins. */
     destroy(): void;
 }

package/dist/helpers/mcp.d.ts

@@ -11,7 +11,12 @@ import type { AgentTool } from '../agent/types';
 import { McpClient } from '../plugins/mcp/client';
 import { type McpAuthProvider } from '../plugins/mcp/oauth';
 import type { SsrfGuardOptions } from '../plugins/mcp/url-guard';
-import { type McpSamplingConfig } from '../plugins/mcp/sampling';
+import { type McpSamplingConfig, type McpSamplingHandler } from '../plugins/mcp/sampling';
+/** Build a sampling handler that fulfils an MCP server's `sampling/createMessage`
+ *  with our own engine. Thin wiring: the MCP-shape mapping lives in
+ *  `plugins/mcp/sampling`, which cannot import this layer without closing a
+ *  dependency cycle, so the completion function is passed down instead. */
+export declare function samplingHandler(config: McpSamplingConfig): McpSamplingHandler;
 import { type McpElicitRequestParams, type McpElicitResult, type McpInitializeResult, type McpRoot, type McpServerConfig } from '../plugins/mcp/types';
 import { type EngineHandle } from './engine';
 export interface ConnectMcpOptions {

package/dist/helpers/models.d.ts

@@ -9,7 +9,7 @@
  *  `{ raw: true }` for bare id strings. Results are cached IN MEMORY for 24h
  *  (override with `refresh: true`). */
 import type { ProviderName } from '../llm/types/provider';
-import type { ModelInfo } from '../plugins/model-catalog/catalog';
+import type { ModelInfo } from '../catalog/catalog';
 import { type EngineHandle } from './engine';
 /** Curated local catalog (the main answer). */
 export declare function listModels(opts?: {

package/dist/helpers/one-shot.d.ts

@@ -15,7 +15,7 @@
  *  LLMClient.complete. Either way the helper destroys its created client
  *  before returning so callers don't leak. */
 import type { AgentTool } from '../agent/types';
-import type { CacheConfig, ThinkingConfig } from '../llm/types/request';
+import type { CacheConfig, ProviderOptions, ThinkingConfig } from '../llm/types/request';
 import type { LLMClientConfig } from '../llm/client-config';
 import type { AudioOptions } from '../llm/types/audio';
 import type { ContentPart, Message } from '../llm/types/messages';
@@ -84,7 +84,7 @@ export interface CompleteOptions {
     /** Optional engine to use. Falls back to coreRegistry default. */
     engine?: EngineHandle;
     /** Provider-specific request options (e.g. `{ openrouter: { models: [...] } }`). */
-    providerOptions?: Record<string, unknown>;
+    providerOptions?: ProviderOptions;
     /** Extra LLMClient options. */
     client?: Partial<Omit<LLMClientConfig, 'provider' | 'model' | 'apiKey'>>;
     /** When set, `estimate()` runs BEFORE the request is sent. If the cost for

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

@@ -11,7 +11,7 @@
  *  Availability-aware: only considers providers with a configured API key.
  *  Ranks cheapest-first (tiebreak: newest version); select() returns the single
  *  best, selectModels() the ranked list. Thresholds + custom tags are overridable. */
-import type { ModelInfo } from '../plugins/model-catalog/catalog';
+import type { ModelInfo } from '../catalog/catalog';
 import type { ProviderName } from '../llm/types/provider';
 import { type EngineHandle } from './engine';
 export interface SelectPrefs {