@combycode/llm-sdk 2.2.2 → 3.0.0

package/MIGRATION.md

@@ -1,3 +1,133 @@
+# Migrating to 3.0.0
+
+**Almost certainly no source changes.** One type member was removed, and it was one the SDK
+set for its own adapters to read — not something an application was ever expected to write.
+
+## `ModelInfo.wire`, `NormalizedRequest.wire` and the `ModelWire` type are gone
+
+`wire` carried per-model traits (`{ thinking, topK }`) that told an adapter which shape a model
+takes. `ModelInfo.wireSpec` — which names the wire spec that builds the request — now carries the
+same knowledge, and it carries it exactly once.
+
+That duplication was the point of removing it. Two representations of one fact drift apart, and
+this library has already shipped two bugs from precisely that: 2.2.1 sent Anthropic the retired
+`thinking` shape, and 2.2.2 sent Gemini tool schemas on the wrong field. Keeping `wire` alongside
+`wireSpec` would have been the same mistake with better tests.
+
+**What to do:** nothing, unless you read `.wire` off a catalog entry. If you did:
+
+```ts
+// before
+const shape = catalog.get('anthropic', model)?.wire?.thinking;   // 'adaptive' | 'budgeted'
+
+// after — the pin names the spec, and the spec defines the shape
+const spec = catalog.get('anthropic', model)?.wireSpec;          // 'anthropic/messages@4.7'
+```
+
+If you were SETTING `wire` on a custom catalog entry to steer an adapter, set `wireSpec` instead:
+
+```ts
+catalog.set('anthropic', 'my-model', { pricing: {}, wireSpec: 'anthropic/messages@4.1' });
+```
+
+**Behaviour is unchanged.** Every catalogued model produces the byte-identical request it produced
+in 2.3.0 — checked on every CI run against a corpus frozen from the 2.3.0 tag: 290 subjects across
+23 request shapes, on both the pinned and the id-derived route.
+
+## The catalog is loaded by default
+
+`createEngine()` and `LLMClient` now start with the bundled provider catalogs instead of an empty
+one. **Almost certainly no source change** — and if you were already passing `catalog: 'defaults'`,
+that still works and now says the same thing twice.
+
+What changes if you were NOT passing it: prices become known, token counts can use the exact
+strategies, and requests are built from the model's wire-spec pin rather than from a rule over its
+id. All three were falling back before, silently.
+
+```ts
+// before — an empty catalog unless you asked
+const engine = createEngine({ apiKeys });            // no pricing, no pins
+const engine = createEngine({ apiKeys, catalog: 'defaults' });  // the data
+
+// after — the data, unless you opt out
+const engine = createEngine({ apiKeys });            // the data
+const engine = createEngine({ apiKeys, catalog: false });       // no entries, on purpose
+```
+
+If you relied on an empty catalog — to be certain no bundled price was used, say — pass
+`catalog: false` (or `'empty'`).
+
+## The token-count APIs need the engine's fetch
+
+`AnthropicCountApi` and `GoogleCountApi` used to default their second argument to
+`globalThis.fetch`. That default is gone: the fetch is required, and it is an `EngineFetch` — the
+same request-object fetch every other adapter takes — rather than a WHATWG `(url, init)` one.
+
+**Almost certainly no source change.** `countTokens()` and `HybridTokenCounter` build these for you,
+and `countTokens()` passes `engine.fetch`. You only touch this if you construct one directly:
+
+```ts
+// before — went around the NetworkEngine entirely
+const api = new AnthropicCountApi(apiKey);
+
+// after
+const api = new AnthropicCountApi(apiKey, engine.fetch);
+```
+
+If you build a `HybridTokenCounter` yourself and want the exact count APIs, pass `fetch`:
+
+```ts
+new HybridTokenCounter({ catalog, countApiKeys, fetch: engine.fetch });
+```
+
+Without it the exact strategies are unavailable and counting falls back to the heuristic, with a
+warning — rather than quietly calling the provider outside the queue, the rate limiter, the retry
+policy and the telemetry, which is what the old default did.
+
+## `hooks.onAny` receives one event instead of `(name, ctx)`
+
+Only affects code that subscribes to the WHOLE event stream. `hooks.on('onCompletion', h)` — the
+named subscription — is unchanged.
+
+```ts
+// before
+hooks.onAny((name, ctx) => {
+  if (name === 'onCompletion') {
+    const c = ctx as { response?: { usage?: { inputTokens?: number } } };
+    record(c.response?.usage?.inputTokens ?? 0);
+  }
+});
+
+// after — `event.type` narrows `event.ctx`, so the cast is gone
+hooks.onAny((event) => {
+  if (event.type === 'onCompletion') {
+    record(event.ctx.response.usage?.inputTokens ?? 0);
+  }
+});
+```
+
+The old shape forced every subscriber to cast, and a cast keeps compiling after the field it names
+is renamed — which for a usage or cost field is a metric that silently reads zero. `HookEvent` is
+derived from `HookMap`, so a hook added later becomes a variant your `switch` is told about.
+
+## Google requests carry the API key in a header, not the URL
+
+Behaviour, not signature: no source change, and no key of yours moves. Twelve Google endpoints —
+files, batch, media, embeddings, count — used to append `?key=…` to the URL; they now send
+`x-goog-api-key`. Nothing to update unless something in your infrastructure reads the key OUT of
+the URL: an allowlist matching on the query string, a log scrubber written against `key=`, or a
+proxy that routes on it. Those stop seeing it, which was the point — a URL travels through logs,
+proxies and error reports that a header does not.
+
+## Nothing else was removed
+
+The band helpers that went with it — `anthropicThinkingShape`, `anthropicAcceptsTopK`,
+`googleUsesThinkingBudget`, and the thinking-budget tables — were never exported from the package
+entry point, and the `exports` map has always blocked deep imports, so no application could reach
+them. They now live as data in `src/wire/pins/`, which is what the Python and Rust ports read.
+
+---
+
 # Migrating to 2.0.0
 
 **Most codebases need no source changes.** The point of this library is that provider churn is our

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/bus/hook-bus.d.ts

@@ -12,9 +12,19 @@
  *  swallow — emitters need to know if a critical handler (like ContextGuard
  *  abort) failed. Plugins that should never break the request must catch
  *  their own errors. */
-import type { HookHandler, HookMap, HookName } from './hook-map';
-/** Catch-all handler: receives the event name + context for EVERY emit. */
-export type AnyHookHandler = (name: HookName, ctx: unknown) => void | Promise<void>;
+import type { HookEvent, HookHandler, HookMap, HookName } from './hook-map';
+/** Catch-all handler: receives EVERY emit as one discriminated union.
+ *
+ *  It used to receive `(name, ctx: unknown)`, which pushed the type back onto the
+ *  subscriber — and the SDK's own telemetry adapter, the only consumer, answered
+ *  the way anyone would: `ctx as Record<string, unknown>`, then a cast per field —
+ *  26 of them in one method.
+ *  Renaming a context field left those reads compiling and silently `undefined`,
+ *  which for the token and cost fields means a metric that quietly goes to zero.
+ *
+ *  With `HookEvent`, `e.type` narrows `e.ctx` and those casts stop being possible
+ *  to write. */
+export type AnyHookHandler = (event: HookEvent) => void | Promise<void>;
 export declare class HookBus {
     private handlers;
     private anyHandlers;

package/dist/bus/hook-map.d.ts

@@ -621,3 +621,27 @@ export interface HookMap {
 }
 export type HookName = keyof HookMap;
 export type HookHandler<K extends HookName> = (ctx: HookMap[K]) => void | Promise<void>;
+/** One event, as a value. `HookMap` types a SUBSCRIPTION (`on('onCompletion', h)`
+ *  knows its own ctx); this types the STREAM, where the name is not known until
+ *  runtime and the payload has to travel with it.
+ *
+ *  Derived from `HookMap` rather than written out, so the 51 variants cannot drift
+ *  from the 51 hooks: adding an entry above adds a variant here, and a consumer
+ *  switching exhaustively over `type` stops compiling until it handles the new one.
+ *
+ *      hooks.onAny((e) => {
+ *        if (e.type === 'onCompletion') e.ctx.response.usage;   // narrowed
+ *      });
+ *
+ *  The payload stays nested under `ctx` instead of being spread onto the event.
+ *  Spreading would collide with the contexts that already carry their own `type`
+ *  field, and would copy an object on every emit — including the per-chunk ones. */
+export type HookEventOf<K extends HookName> = {
+    readonly type: K;
+    readonly ctx: HookMap[K];
+};
+/** The SDK's whole event stream as a single discriminated union — the portable
+ *  shape: a Rust enum, a Python tagged union, a TS union, all from one catalog. */
+export type HookEvent = {
+    [K in HookName]: HookEventOf<K>;
+}[HookName];

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

@@ -94,6 +94,17 @@ 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[];
+    /** 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 |
@@ -156,6 +167,14 @@ export declare class ModelCatalog {
     isStateModelBound(provider: string, model: string): boolean;
     list(provider?: string): ModelInfo[];
     load(data: Record<string, unknown>): void;
+    /** A catalog with every bundled provider entry already loaded.
+     *
+     *  This is what the engine and the client build when nobody says otherwise. A
+     *  fresh instance each time rather than a shared one: the catalog is mutable
+     *  (`set()` is public and examples use it), so sharing would let one engine's
+     *  edit reach another's request. Indexing all 427 entries costs about a
+     *  millisecond, against a network call. */
+    static withProviderDefaults(): ModelCatalog;
     /** Load every provider's `catalog.json` shipped with the SDK. Synchronous —
      *  the JSON files are bundled via static import so no I/O at runtime. */
     loadProviderDefaults(): void;

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. */
@@ -46,8 +46,27 @@ export declare class ClientResolver {
 export declare function parseModelId(modelId: string): [ProviderName, string];
 export declare function isNamespacedModelId(modelId: string): boolean;
 /** Resolve a model + optional provider to a concrete { provider, model }.
- *  A namespaced id ("provider/model") yields its own provider; a bare model
- *  requires an explicit `provider`. `label` names the caller in the error. */
+ *
+ *  An EXPLICIT provider always wins. It used to lose to the model's prefix, and
+ *  that is not a preference — every OpenRouter model id is `vendor/model`, so
+ *  `createLLM({ provider: 'openrouter', model: 'openai/gpt-5.4-nano' })` resolved
+ *  to the provider `openai` and sent the **OpenRouter key to api.openai.com**.
+ *  Ids whose vendor is not one of our five (`qwen/qwen3`) fared differently and no
+ *  better: the prefix was cast to a ProviderName and failed later as "no default
+ *  adapter for provider 'qwen'".
+ *
+ *  With a provider given, a leading `<provider>/` on the model is redundant and is
+ *  stripped — `openrouter` + `openrouter/openai/gpt-5.4-nano` is the catalog's own
+ *  slug form and means the OpenRouter model `openai/gpt-5.4-nano`.
+ *
+ *  Without one, the `provider/model` prefix is still the documented sugar, and it
+ *  stays permissive about the prefix on purpose: the pricing paths (`estimate`,
+ *  `estimator`) resolve models that are catalogued under a provider nobody can
+ *  CALL — a private deployment, a test fixture — and rejecting those would break
+ *  costing a model you never send. A prefix that is not callable fails where it
+ *  matters, in the adapter factory, naming the provider it could not build.
+ *
+ *  `label` names the caller in the error. */
 export declare function resolveModel(model: string, provider: ProviderName | undefined, label: string): {
     provider: ProviderName;
     model: string;

package/dist/helpers/count-tokens.d.ts

@@ -17,7 +17,7 @@ export interface CountTokensOptions {
     provider?: ProviderName;
     /** Text or messages to count. */
     input: string | Message[];
-    /** Key for the exact count-API path (Anthropic/Google). Falls back to engine.apiKeys. */
+    /** Key for the exact count-API path (Anthropic, Google, xAI). Falls back to engine.apiKeys. */
     apiKey?: string;
     /** Use the precise counter where available (default true). false = sync estimate. */
     exact?: boolean;

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,18 @@ export interface EngineHandle {
      *  createMediaOutput, complete) read these to wire LLM clients without
      *  the caller passing apiKey explicitly. */
     apiKeys: Partial<Record<ProviderName, string>>;
+    /** Whether clients built from this engine check response shapes. Read by
+     *  `createLLM`; see `checkResponseShapes` on the options. */
+    checkResponseShapes: boolean;
+    /** 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;
 }
@@ -89,12 +103,31 @@ export interface EngineConfig {
     /** Custom low-level fetch transport — forwarded to the NetworkEngine's queue
      *  (so retry/rate-limit/hooks still apply). Defaults to globalThis.fetch. */
     fetch?: FetchFn;
-    /** Catalog wiring. Pass:
-     *    - `true` / 'defaults' → load every bundled provider catalog.json
+    /** Warn when a provider's response stops looking like the one we learned to
+     *  read: a field never seen before, a field that was always present and is now
+     *  absent, or a discriminator carrying a value nothing branches on.
+     *
+     *  OFF by default. It never changes what is parsed — it only emits `onWarning`,
+     *  so subscribe with `hooks.on('onWarning', …)` and look for codes starting
+     *  `response_shape_`. Each distinct finding is reported ONCE per client.
+     *
+     *  Worth turning on in staging and in your test suite: response drift is the
+     *  failure this library gives you the least warning about, because a renamed
+     *  field still parses — into `undefined`. */
+    checkResponseShapes?: boolean;
+    /** Catalog wiring. **Defaults to the bundled provider catalogs.**
+     *
+     *  The catalog is what the adapters read per model: which wire spec builds the
+     *  request, what the model costs, which tokenizer counts it. Starting empty
+     *  meant every one of those silently fell back — the id-derived spec, an
+     *  unknown price, an estimated token count — and nothing said so. The data is
+     *  statically imported either way, so leaving it unloaded saved no bytes.
+     *
+     *    - undefined (default) / `true` / 'defaults' → every bundled catalog.json
      *    - existing ModelCatalog instance → use as-is
-     *    - `{ entries: {...} }` → build empty + load() the entries
-     *    - undefined → empty catalog */
-    catalog?: ModelCatalog | true | 'defaults' | {
+     *    - `{ entries: {...} }` → the given entries only
+     *    - `false` / 'empty' → no entries. Everything falls back; say so on purpose. */
+    catalog?: ModelCatalog | boolean | 'defaults' | 'empty' | {
         entries: Record<string, unknown>;
     };
     /** Per-provider API keys. Helpers consult this when no apiKey is passed

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 {