@combycode/llm-sdk 2.3.0 → 3.0.0

package/dist/plugins/mcp/transport-http.d.ts

@@ -62,13 +62,19 @@ export declare class HttpTransport extends BaseJsonRpcTransport implements McpTr
      *  two. The eventual JSON-RPC response has no pending entry to settle — its only meaning is "the
      *  stream ended", which is reported through `onEnd`. */
     sendLongLivedRequest(method: string, params?: unknown, onEnd?: (error?: unknown) => void): Promise<number>;
-    private headers;
-    /** Modern-era routing headers: `Mcp-Method` on every request, plus `Mcp-Name` carrying the
-     *  method's subject (tool name / prompt name / resource URI) so a gateway can route and
-     *  authorize without parsing the body. No-op on the handshake wire. */
-    private routingHeaders;
-    /** Base headers + any OAuth bearer + per-call extras. */
-    private authedHeaders;
+    /** The shared registry plus the two rules only MCP has. */
+    private readonly wireRegistry;
+    /** Build one MCP request from its spec.
+     *
+     *  Everything that varies — the negotiated era, the session, the declared
+     *  protocol version, a resolved bearer, the resumption cursor — is passed IN, so
+     *  the spec decides which headers those facts produce. That decision used to be
+     *  spread across three private helpers and the order in which their results were
+     *  spread into an object literal.
+     *
+     *  `provider` / `model` route and queue the call inside the NetworkEngine and are
+     *  not part of the wire, so they wrap the spec's output. */
+    private request0;
     private post;
 }
 /** Extract the JSON-RPC response matching `id` from a JSON or SSE body. */

package/dist/plugins/mcp/wire-rules.d.ts

@@ -0,0 +1,21 @@
+/** The two MCP rules a spec cannot express as data, and where they live.
+ *
+ *  Every other named spec rule sits in `src/llm/wire-transforms.ts`, but these
+ *  cannot: `llm -> plugins` is a forbidden edge (the layer test names it), and MCP
+ *  is a plugin. So the transport composes its own registry from the shared one
+ *  rather than the shared one reaching down into MCP.
+ *
+ *  Both are genuinely code rather than data:
+ *
+ *  `mcpModern` — era is set only AFTER discovery succeeds, so a request has to be
+ *  judged by the version it DECLARES as well. Keying on era alone left the
+ *  `server/discover` probe itself half-modern, which a modern server rejects.
+ *
+ *  `mcpNameHeader` — the subject lives under a different param per method (`name`
+ *  for tools/call and prompts/get, `uri` for resources/read), so this is a lookup
+ *  followed by a read at the key that lookup returned. A template can express a
+ *  fixed path, not a computed one.
+ */
+import type { Registry } from '../../wire/interpreter';
+/** Add the MCP rules to a base registry, leaving the base untouched. */
+export declare function mcpWireRegistry(base: Registry): Registry;

package/dist/plugins/retrieval/document-file.d.ts

@@ -0,0 +1,15 @@
+/** The upload part for a document: its bytes, and a name for them.
+ *
+ *  All three hosted backends upload a document the same way — the text as a
+ *  `text/plain` file — and all three had their own copy of this, which is how they
+ *  came to disagree about nothing yet still had to be fixed three times.
+ *
+ *  The fallback name is derived from the CONTENT. It used to be a random UUID,
+ *  which made the request unreproducible: it could not be asserted in a test,
+ *  frozen in a fixture, or matched against a log, and a retried upload arrived
+ *  under a different name every time. A content hash keeps a retry idempotent
+ *  while still separating two different documents.
+ */
+import type { MultipartFile } from '../../llm/wire-multipart';
+import type { DocumentSource } from './types';
+export declare function documentFile(source: DocumentSource): MultipartFile;

package/dist/plugins/retrieval/hosted-google.d.ts

@@ -38,9 +38,14 @@ export declare class HostedGoogleRetrievalBackend implements RetrievalBackend {
     private readonly fetch;
     private readonly baseURL;
     constructor(config: HostedGoogleRetrievalConfig);
-    private authHeaders;
-    /** Auth headers for multipart/form-data file upload (no content-type override). */
-    private authHeadersNoContentType;
+    /** File-search rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one file-search request from its spec, then add the engine metadata.
+     *
+     *  `provider` / `model` / `responseType` route and queue the call inside the
+     *  NetworkEngine; they are not part of the wire, so they wrap the spec's output
+     *  rather than being described by it. */
+    private request;
     createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
     addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
     /** Poll a long-running Operation until done: true.

package/dist/plugins/retrieval/hosted-openai.d.ts

@@ -29,7 +29,15 @@ export declare class HostedOpenAIRetrievalBackend implements RetrievalBackend {
     private readonly fetch;
     private readonly baseURL;
     constructor(config: HostedOpenAIRetrievalConfig);
-    private bearer;
+    /** Vector-store rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one vector-store request from its spec, then add the engine metadata.
+     *
+     *  `provider` / `model` / `responseType` are how the NetworkEngine routes and
+     *  queues the call — they are not part of the wire, so they are wrapped around
+     *  the spec's output rather than described by it. A multipart spec names the
+     *  fields but not the bytes, so an upload passes its file in here. */
+    private request;
     createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
     addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
     indexStatus(corpus: CorpusRef): Promise<IndexStatus>;

package/dist/plugins/retrieval/hosted-xai.d.ts

@@ -41,8 +41,14 @@ export declare class HostedXaiRetrievalBackend implements RetrievalBackend {
     private readonly baseURL;
     private readonly managementBaseURL;
     constructor(config: HostedXaiRetrievalConfig);
-    private stdBearer;
-    private mgmtBearer;
+    /** Collection rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one collections request from its spec, then add the engine metadata.
+     *
+     *  BOTH planes are handed to every spec: which host and which key a call uses is
+     *  a property of the ENDPOINT, so the spec decides it rather than the caller
+     *  picking a bearer helper and hoping it matches the URL it typed. */
+    private request;
     createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
     addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
     indexStatus(corpus: CorpusRef): Promise<IndexStatus>;

package/dist/wire/chat-specs.d.ts

@@ -0,0 +1,32 @@
+/** The wire specs the RUNTIME loads: chat only, resolved and memoised.
+ *
+ *  Deliberately not `registry.ts`. That index imports all 71 specs — every media,
+ *  realtime, files and batch spec included — so an adapter importing it would pull
+ *  the whole set into every bundle whether or not anything reads them. Measured on
+ *  the 2.3.0 build: interpreter + inherit + transforms is 18 KB minified, the nine
+ *  chat specs add 15 KB, and all 71 specs add 41 KB. Chat-only is +2.7% on the
+ *  bundle; everything is +4.8% for specs nothing executes yet.
+ *
+ *  `registry.ts` stays as the complete index for the tests and the ports. This is
+ *  the runtime's subset, and it grows a family at a time as each adapter is
+ *  migrated — so what ships is always what runs.
+ *
+ *  Chains are resolved once per id and cached: resolution walks `extends` and
+ *  merges deltas, which is pure setup work and has no business happening per
+ *  request.
+ */
+import type { WireSpec } from './interpreter';
+/** The spec for `id`, with its inheritance chain already applied.
+ *
+ *  Throws on an unknown id rather than falling back to something plausible: a
+ *  silently-substituted spec is a wrong request sent confidently, which is the
+ *  exact failure the specs exist to end. Callers pick the fallback themselves —
+ *  see each adapter's DEFAULT_SPEC. */
+export declare function chatSpec(id: string): WireSpec;
+/** Whether a spec id is one the runtime can build. Lets an adapter fall back to
+ *  its default instead of throwing when a catalog pin names a spec from a family
+ *  that is not migrated yet. */
+export declare const isChatSpec: (id: string | undefined) => id is string;
+/** Ids the runtime carries — asserted by the tests so this list and the shipped
+ *  spec files cannot drift apart unnoticed. */
+export declare const CHAT_SPEC_IDS: readonly string[];

package/dist/wire/inherit.d.ts

@@ -32,10 +32,6 @@ export interface Deltas {
 export type SpecDelta = Partial<WireSpec> & Deltas & {
     id: string;
 };
-/** Apply one delta to a resolved spec. This is the whole of composition, and it
- *  is deliberately shared: a CHAIN picks the delta sequence by walking parents, a
- *  MATRIX picks it by selecting features. Behind the resolver they are the same
- *  operation — see `compose.ts`. */
 export declare function applyDelta(base: WireSpec, delta: SpecDelta): WireSpec;
 /** Resolve a spec id to its fully flattened form by walking `extends`. */
 export declare function resolveSpec(id: string, byId: Map<string, SpecDelta>, seen?: Set<string>): WireSpec;

package/dist/wire/interpreter.d.ts

@@ -108,12 +108,43 @@ export interface WireSpec {
         /** `json` (default), `multipart`, or `none` for GET/DELETE with no body.
          *  Multipart matters: a FormData body JSON-stringifies to `{}`, so comparing
          *  it as JSON would pass vacuously no matter what the fields are. */
-        bodyKind?: 'json' | 'multipart' | 'none';
+        /** `json` (default), `multipart`, `none` for a bodyless GET/DELETE, or
+         *  `raw` when the body is caller-supplied BYTES the spec cannot describe —
+         *  a file being streamed to an upload session. The spec still owns the URL,
+         *  method and headers; only the payload comes from outside. */
+        bodyKind?: 'json' | 'multipart' | 'none' | 'raw' | 'form';
+        /** Headers in declaration order. An entry with `spread` merges an evaluated
+         *  OBJECT of headers instead of setting one, which is what a caller-supplied
+         *  header map or a resolved auth bundle is. Order is the whole point: it is
+         *  what decides whether a configured `accept` overrides the default one or the
+         *  other way round, and that was previously a property of which spread came
+         *  later in a hand-written object literal. */
         headers?: {
+            name?: string;
+            value?: Json;
+            when?: Cond;
+            spread?: Json;
+        }[];
+        /** Query parameters, appended to `url` (or `path`) in declaration order.
+         *
+         *  Splicing them into the URL with `$join` works only while every parameter is
+         *  present: `$join` propagates an omitted part, so one absent `pageToken` takes
+         *  the whole URL with it. Declaring them separately lets a parameter drop out
+         *  on its own, and puts the encoding in ONE place — the hand-written adapters
+         *  disagreed about whether to call `encodeURIComponent`, which is how a page
+         *  token with a `+` in it silently paged from the wrong place. */
+        query?: {
             name: string;
             value: Json;
             when?: Cond;
         }[];
+        /** How query values are escaped. `component` (default) percent-escapes
+         *  everything, including a space as `%20`. `form` uses the
+         *  application/x-www-form-urlencoded rules, where a space is `+` — which is
+         *  what RFC 6749 prescribes for an OAuth authorization request, and what its
+         *  servers are used to receiving. Both decode to the same string; they are not
+         *  the same bytes, and a signature over the request would notice. */
+        queryEncoding?: 'component' | 'form';
     };
     /** Model-id → variant flags. The migration target is a catalog pin; the
      *  `idMatch` form is what today's regex helpers do, expressed as data.
@@ -141,6 +172,11 @@ export interface WireSpec {
         value?: Json;
         file?: boolean;
         when?: Cond;
+        /** Emit ONE field per array element instead of a single array-valued
+         *  field. Real forms use repeated keys for lists — OpenAI's transcription
+         *  takes `languages[]` once per language — and a single field holding an
+         *  array is a different request the server will not accept. */
+        repeat?: boolean;
     }[];
     /** Non-HTTP surfaces. A realtime session is not one request: it is a
      *  connection descriptor plus a sequence of outbound frames, so those are
@@ -205,8 +241,15 @@ export interface BuiltRequest {
     path?: string;
     url?: string;
     method?: string;
+    /** The body is caller-supplied bytes (bodyKind 'raw'). */
+    rawBody?: boolean;
     /** Present instead of a JSON body when bodyKind is 'multipart'. */
     multipart?: MultipartField[];
+    /** The body is form-urlencoded: `body` holds the FIELDS, and the caller encodes
+     *  them. Same split as multipart — the spec says what the form carries, the
+     *  runtime does the encoding, and the frozen fixture stays readable as fields
+     *  rather than as one percent-escaped string. */
+    formBody?: boolean;
     /** True when the spec declares the request carries no body at all. */
     noBody?: boolean;
 }

package/dist/wire/mcp-specs.d.ts

@@ -0,0 +1,13 @@
+/** The MCP Streamable-HTTP spec family.
+ *
+ *  A sibling of the provider families, loaded separately for the same reason: an
+ *  application that never talks to an MCP server should not carry these, and the
+ *  generated `registry.ts` imports everything.
+ *
+ *  MCP is the case that shows the spec format is about NETWORKING rather than about
+ *  LLM providers — a JSON-RPC envelope, era-dependent routing headers and a
+ *  long-lived stream are described by the same six constructs a chat request uses.
+ */
+import type { WireSpec } from './interpreter';
+/** Resolve an MCP spec by id, flattening its `extends` chain. */
+export declare function mcpSpec(id: string): WireSpec;

package/dist/wire/media-specs.d.ts

@@ -0,0 +1,20 @@
+/** The media wire specs the RUNTIME loads, resolved and memoised.
+ *
+ *  A sibling of `chat-specs.ts` and separate from it for the same reason that file
+ *  is separate from `registry.ts`: the generated index imports all 71 specs, so any
+ *  adapter reaching for it pulls in every family whether or not anything runs them.
+ *  The runtime loads one family at a time, as each is migrated, so what ships is
+ *  what executes.
+ *
+ *  Only the leaves are exported — the `*.base` specs exist to be inherited from and
+ *  are never built directly, so naming one is a mistake worth catching.
+ */
+import type { WireSpec } from './interpreter';
+/** The media spec for `id`, with its inheritance chain applied.
+ *
+ *  Throws on an unknown or abstract id rather than substituting something
+ *  plausible: a quietly wrong endpoint is the failure mode the specs exist to end. */
+export declare function mediaSpec(id: string): WireSpec;
+/** Buildable media spec ids — asserted by the tests so this list and the shipped
+ *  spec files cannot drift apart unnoticed. */
+export declare const MEDIA_SPEC_IDS: readonly string[];

package/dist/wire/pins.d.ts

@@ -0,0 +1,34 @@
+/** Which spec builds a model's request when the catalog has no pin for it.
+ *
+ *  Every catalogued model carries an explicit `wireSpec`, so this only decides for
+ *  the models the catalog does not know: one released after this build, or an
+ *  engine running without a catalog at all. That case is not an edge — it is how
+ *  the SDK works on the day a provider ships something new — so it keeps a real
+ *  answer rather than a guess.
+ *
+ *  It is DATA, not code, for the same reason the specs are: the Python and Rust
+ *  ports read this file instead of each re-implementing version arithmetic and
+ *  drifting from it. Two versions of that arithmetic is exactly how the 2.2.1
+ *  regression happened.
+ *
+ *  Rules are ordered and the first match wins; `default` answers everything else.
+ */
+export interface PinRule {
+    /** Anchored regular expression, matched against the model id. */
+    match: string;
+    spec: string;
+    /** Why this band exists. Read by humans, not by the resolver. */
+    why?: string;
+}
+export interface ModelPins {
+    id: string;
+    rules?: PinRule[];
+    default: string;
+}
+/** The spec id for `model`, from an ordered rule table.
+ *
+ *  The id is lower-cased and stripped of a `provider/` prefix first, because a
+ *  caller may legitimately pass either form and a band must not depend on which. */
+export declare function pinFor(model: string, pins: ModelPins): string;
+export declare const ANTHROPIC_MESSAGE_PINS: ModelPins;
+export declare const GOOGLE_GENERATE_PINS: ModelPins;

package/dist/wire/registry.d.ts

@@ -5,11 +5,13 @@
  *  is consumed by this SDK and by the Python and Rust ports, and a provider
  *  change is one reviewable diff rather than three code changes.
  *
- *  Generated index — regenerate rather than hand-edit when adding a spec.
+ *  GENERATED by scripts/gen-wire-registry.ts — do not hand-edit. Add a spec by
+ *  dropping the JSON into src/wire/specs/ and running `bun run gen:registry`.
  *
- *  Specs are not yet wired into the adapters: they currently serve as the
- *  differential oracle that proves the hand-written adapters and this data agree
- *  (see tests/unit/wire). Making them authoritative is the 3.0.0 step.
+ *  This index is what the chain tests and the coverage audit enumerate. The
+ *  ADAPTERS do not read it: each family has its own loader (chat-specs,
+ *  media-specs, service-specs, retrieval-specs) so a chat call does not drag
+ *  every batch and media spec into the bundle.
  */
 import type { SpecDelta } from './inherit';
 /** All shipped specs, keyed by `provider/api@version` id. */

package/dist/wire/retrieval-specs.d.ts

@@ -0,0 +1,14 @@
+/** The hosted-retrieval spec family: vector stores, file search stores, collections.
+ *
+ *  A sibling of `chat-specs.ts`, `media-specs.ts` and `service-specs.ts`, split for
+ *  the same reason: the generated `registry.ts` imports all 118 specs, so anything
+ *  reaching for it drags every family into the bundle. An application that never
+ *  builds a corpus should not carry these.
+ *
+ *  Only leaves are buildable. The base specs exist to be inherited from — they
+ *  carry auth and content-type and produce no endpoint of their own — so naming
+ *  one is a mistake to catch, not a request to send.
+ */
+import type { WireSpec } from './interpreter';
+/** Resolve a retrieval spec by id, flattening its `extends` chain. */
+export declare function retrievalSpec(id: string): WireSpec;

package/dist/wire/service-specs.d.ts

@@ -0,0 +1,18 @@
+/** The remaining runtime spec families: embeddings, realtime, batch, files, and
+ *  the media adapters that had no builder seam until now.
+ *
+ *  A sibling of `chat-specs.ts` and `media-specs.ts`, split for the same reason:
+ *  the generated `registry.ts` imports all 71 specs, so an adapter reaching for it
+ *  drags every family into the bundle whether or not anything executes them. Each
+ *  file here loads exactly what its adapters run.
+ *
+ *  Only leaves are buildable. The `*.base` specs exist to be inherited from and
+ *  produce no endpoint of their own, so naming one is a mistake to catch rather
+ *  than a request to send.
+ */
+import type { WireSpec } from './interpreter';
+/** The service spec for `id`, with its inheritance chain applied. Throws on an
+ *  unknown or abstract id rather than substituting something plausible. */
+export declare function serviceSpec(id: string): WireSpec;
+/** Buildable ids, asserted by the tests so this list cannot drift from the files. */
+export declare const SERVICE_SPEC_IDS: readonly string[];

package/dist/wire/utility-specs.d.ts

@@ -0,0 +1,10 @@
+/** The utility spec family: exact token counting, live model listing, file
+ *  content retrieval, and the provenance check.
+ *
+ *  Four small surfaces that share nothing except being requests. They are loaded
+ *  together because each is a handful of specs and no consumer reaches one without
+ *  reaching the layer that owns it.
+ */
+import type { WireSpec } from './interpreter';
+/** Resolve a utility spec by id, flattening its `extends` chain. */
+export declare function utilitySpec(id: string): WireSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",
@@ -43,8 +43,11 @@
     "format": "biome format --write src tests",
     "check": "biome check src tests",
     "check:fix": "biome check --write src tests",
+    "gen:registry": "bun run scripts/gen-wire-registry.ts",
     "gate": "bun run scripts/gate.ts",
     "gate:selftest": "node ../../quality-gate/selftest.mjs",
+    "record:responses": "bun run scripts/record-responses.ts",
+    "derive:shapes": "bun run scripts/derive-response-shapes.ts",
     "gate:snapshot": "bun run scripts/gate.ts --only api-snapshot --update"
   },
   "devDependencies": {