@combycode/llm-sdk 2.3.0 → 3.1.0

package/dist/llm/providers/openai/transcription.d.ts

@@ -15,7 +15,7 @@
  *  No model returns everything: speaker labels and word timings live on different
  *  models. `keywords` / `languages` are `gpt-transcribe`-only and 400 elsewhere. */
 import type { TranscriptLanguage, TranscriptSegment, TranscriptWord } from '../../types/audio';
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 export interface OpenAITranscriptionAdapterConfig {
     apiKey: string;
     baseURL?: string;
@@ -52,6 +52,12 @@ export declare class OpenAITranscriptionAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAITranscriptionAdapterConfig);
+    /** Named code these specs need. */
+    private readonly wireRegistry;
+    /** The multipart spec names the FIELDS; the audio bytes come from the request.
+     *  `wordTimestamps` with `diarization` is rejected before this point: they select
+     *  different response formats and no model serves both. */
+    buildTranscribeRequest(req: TranscriptionRequest): HttpRequest;
     transcribe(req: TranscriptionRequest, fetch: EngineFetch): Promise<OpenAITranscriptionResult>;
 }
 export declare function parseTranscription(body: unknown): OpenAITranscriptionResult;

package/dist/llm/providers/openrouter/completions.d.ts

@@ -1,7 +1,6 @@
 /** OpenRouter provider adapter — OpenAI-compatible with extensions. */
 import type { SSEEvent } from '../../../network/types';
-import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
-import type { NormalizedRequest } from '../../types/request';
+import type { ProviderAdapter } from '../../types/provider';
 import type { CompletionResponse } from '../../types/response';
 import type { StreamEvent } from '../../types/stream';
 import { OpenAIAdapter } from '../openai/completions';
@@ -14,7 +13,10 @@ export declare class OpenRouterAdapter extends OpenAIAdapter {
     constructor(config: OpenRouterAdapterConfig);
     baseURL(): string;
     completionPath(): string;
-    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** Everything this class used to do to `super.buildRequest()` — the max_tokens
+     *  rename, the reasoning strip, the tier remap, the routing passthrough — is the
+     *  `openrouter` overlay in the shared spec. Naming the flavor IS the override now. */
+    protected readonly wireFlavor: string;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     /** Stateful — emit a single `web_search` builtin-tool pair the first time
      *  `url_citation` annotations appear in the stream (the `:online` search signal). */

package/dist/llm/providers/openrouter/embeddings.d.ts

@@ -4,4 +4,7 @@ export declare class OpenRouterEmbeddingAdapter extends OpenAIEmbeddingAdapter {
     readonly name: string;
     constructor(config: OpenAIEmbeddingAdapterConfig);
     protected embeddingsPath(): string;
+    /** The whole OpenRouter delta is the URL, so the spec that carries it is the
+     *  whole override. */
+    protected specId(): string;
 }

package/dist/llm/providers/openrouter/media.d.ts

@@ -2,7 +2,7 @@
  *  image (and audio) generation go through `POST /api/v1/chat/completions` with
  *  a `modalities` field; output comes back on `message.images[]` /
  *  `message.audio`. Cost is the provider-reported `usage.cost`. */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult } from '../../../plugins/media/types';
 export interface OpenRouterMediaAdapterConfig {
     apiKey: string;
@@ -14,12 +14,22 @@ export declare class OpenRouterMediaAdapter implements MediaProviderAdapter {
     private readonly baseURL;
     constructor(config: OpenRouterMediaAdapterConfig);
     capabilities(): MediaCapabilities;
-    private authHeaders;
+    /** Named code the specs cannot express as data — the data-URL and image_config. */
+    private readonly wireRegistry;
+    /** Build one request from its spec, then add the engine metadata. */
+    private fromSpec;
+    /** Text-to-image. OpenRouter has no image endpoint: images come back from
+     *  chat/completions with `modalities: ['image','text']`. */
+    buildImageRequest(req: ImageGenRequest, model?: string): HttpRequest;
+    /** Image-to-image: the same call with the source image as a second content part. */
+    buildEditImageRequest(req: ImageEditRequest, model?: string): HttpRequest;
+    /** Audio out, again through chat/completions. */
+    buildAudioRequest(req: AudioGenRequest, model?: string): HttpRequest;
+    /** Exposed for the wire registry: `image_config` from normalised params. */
+    imageConfig(params: ImageGenRequest['params']): Record<string, unknown>;
     generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     editImage(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
-    /** image_config from normalized params (aspect_ratio / image_size / strength). */
-    private imageConfig;
     private chat;
     private chatImage;
 }

package/dist/llm/providers/openrouter/responses.d.ts

@@ -1,8 +1,7 @@
 /** OpenRouter Responses API adapter.
  *  Drop-in replacement for OpenAI Responses API at openrouter.ai/api/v1/responses.
  *  Stateless: no previous_response_id support (beta limitation). */
-import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
-import type { NormalizedRequest } from '../../types/request';
+import type { ProviderAdapter } from '../../types/provider';
 import { OpenAIResponsesAdapter } from '../openai/responses';
 export interface OpenRouterResponsesAdapterConfig {
     apiKey: string;
@@ -13,5 +12,8 @@ export declare class OpenRouterResponsesAdapter extends OpenAIResponsesAdapter {
     constructor(config: OpenRouterResponsesAdapterConfig);
     baseURL(): string;
     completionPath(): string;
-    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** Everything this class used to do to `super.buildRequest()` — the max_tokens
+     *  rename, the reasoning strip, the tier remap, the routing passthrough — is the
+     *  `openrouter` overlay in the shared spec. Naming the flavor IS the override now. */
+    protected readonly wireFlavor: string;
 }

package/dist/llm/providers/xai/batch.d.ts

@@ -1,6 +1,6 @@
 /** xAI batch adapter — create batch, add requests, poll, get results.
  *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { BatchProviderAdapter, BatchRequest, BatchResult, BatchStatus } from '../../../plugins/batch/types';
 export interface XAIBatchAdapterConfig {
     apiKey: string;
@@ -11,7 +11,18 @@ export declare class XAIBatchAdapter implements BatchProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: XAIBatchAdapterConfig);
-    private bearer;
+    /** Batch rules need no adapter handles: the request list is mapped by the spec. */
+    private readonly wireRegistry;
+    /** Build one batch request from its spec, then add the engine metadata.
+     *
+     *  `bodyKind: none` in a spec means no body at all: the interpreter reports that
+     *  as `noBody`, and the engine wants the field simply absent. */
+    private fromSpec;
+    buildCreateRequest(requests: BatchRequest[]): HttpRequest;
+    buildAddRequestsRequest(batchId: string, requests: BatchRequest[]): HttpRequest;
+    buildStatusRequest(batchId: string): HttpRequest;
+    buildCancelRequest(batchId: string): HttpRequest;
+    buildResultsRequest(batchId: string): HttpRequest;
     submit(requests: BatchRequest[], fetch: EngineFetch): Promise<string>;
     getStatus(batchId: string, fetch: EngineFetch): Promise<BatchStatus>;
     getResults(batchId: string, fetch: EngineFetch): Promise<BatchResult[]>;

package/dist/llm/providers/xai/completions.d.ts

@@ -5,8 +5,7 @@
  *  - Returns reasoning_content in message (plain text, unlike OpenAI which hides it)
  */
 import type { SSEEvent } from '../../../network/types';
-import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
-import type { NormalizedRequest } from '../../types/request';
+import type { ProviderAdapter } from '../../types/provider';
 import type { CompletionResponse } from '../../types/response';
 import type { StreamEvent } from '../../types/stream';
 import { OpenAIAdapter, type OpenAIStreamState } from '../openai/completions';
@@ -18,7 +17,10 @@ export declare class XAIAdapter extends OpenAIAdapter {
     readonly name: ProviderAdapter['name'];
     constructor(config: XAIAdapterConfig);
     baseURL(): string;
-    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** Everything this class used to do to `super.buildRequest()` — the max_tokens
+     *  rename, the reasoning strip, the tier remap, the routing passthrough — is the
+     *  `xai` overlay in the shared spec. Naming the flavor IS the override now. */
+    protected readonly wireFlavor: string;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent, state?: OpenAIStreamState): StreamEvent[];
 }

package/dist/llm/providers/xai/files.d.ts

@@ -1,6 +1,6 @@
 /** xAI file adapter — POST /v1/files (purpose=assistants).
  *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { FileAttachment } from '../../../plugins/files/attachment';
 import type { FileProviderAdapter, FileUploadResult, RemoteFileInfo } from '../../../plugins/files/provider-adapter';
 export interface XAIFileAdapterConfig {
@@ -15,7 +15,18 @@ export declare class XAIFileAdapter implements FileProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: XAIFileAdapterConfig);
-    private bearer;
+    /** File rules need no adapter handles. */
+    private readonly wireRegistry;
+    /** Build one file request from its spec, then add the engine metadata.
+     *
+     *  A multipart spec describes the FIELDS but not the bytes, so an upload passes
+     *  its attachment in and the descriptor is filled here. `bodyKind: none` arrives
+     *  as `noBody`; the engine wants the field simply absent. */
+    private fromSpec;
+    buildUploadRequest(file: FileAttachment, data: Uint8Array): Promise<HttpRequest>;
+    buildDeleteRequest(remoteId: string): Promise<HttpRequest>;
+    buildGetInfoRequest(remoteId: string): Promise<HttpRequest>;
+    buildListRequest(): Promise<HttpRequest>;
     upload(file: FileAttachment, fetch: EngineFetch): Promise<FileUploadResult>;
     delete(remoteId: string, fetch: EngineFetch): Promise<void>;
     getInfo(remoteId: string, fetch: EngineFetch): Promise<RemoteFileInfo | null>;

package/dist/llm/providers/xai/media.d.ts

@@ -1,5 +1,5 @@
 /** xAI media adapter — images, TTS, video. All HTTP through EngineFetch. */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult, VideoGenRequest, VideoStatus } from '../../../plugins/media/types';
 export interface XAIMediaAdapterConfig {
     apiKey: string;
@@ -11,7 +11,33 @@ export declare class XAIMediaAdapter implements MediaProviderAdapter {
     private readonly baseURL;
     constructor(config: XAIMediaAdapterConfig);
     capabilities(): MediaCapabilities;
-    private authHeaders;
+    /** Named code the specs cannot express as data — image/video source refs. */
+    private readonly wireRegistry;
+    /** Build one request from its spec, then add the engine metadata.
+     *
+     *  `provider`, `model` and `responseType` are routing and decoding concerns that
+     *  never reach xAI, so the specs do not model them. */
+    private fromSpec;
+    /** Poll a video job. All three xAI video endpoints return a request_id that is
+     *  polled here. */
+    buildVideoStatusRequest(operationId: string): HttpRequest;
+    buildVideoCancelRequest(operationId: string): HttpRequest;
+    /** Fetch bytes from a URL xAI put in its own response - a generated image or a
+     *  finished video. The URL is an input because xAI chose it; the auth headers
+     *  are still ours, which is why it is a spec and not a bare fetch. */
+    buildDownloadRequest(downloadUrl: string, model?: string): HttpRequest;
+    /** Text-to-image. */
+    buildImageRequest(req: ImageGenRequest, model?: string): HttpRequest;
+    /** Image-to-image edit — JSON with a data-URL or file_id, no multipart, no mask. */
+    buildEditImageRequest(req: ImageEditRequest, model?: string): HttpRequest;
+    /** TTS. arraybuffer because the response is audio bytes. */
+    buildAudioRequest(req: AudioGenRequest, model?: string): HttpRequest;
+    /** Video submission, routed by input and mode:
+     *    no sourceVideo                  -> /v1/videos/generations
+     *    sourceVideo + videoMode extend  -> /v1/videos/extensions  (duration only)
+     *    sourceVideo + videoMode edit    -> /v1/videos/edits       (prompt + video)
+     *  Three endpoints with three different field sets, so three specs. */
+    buildVideoRequest(req: VideoGenRequest, model?: string): HttpRequest;
     generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     /** Image-to-image edit via `/v1/images/edits` (JSON; base64 data-URL or
      *  file_id, no multipart, no mask). */
@@ -21,14 +47,6 @@ export declare class XAIMediaAdapter implements MediaProviderAdapter {
     private parseImages;
     generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
     submitVideo(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
-    /** Route a video request to the right xAI endpoint by input + mode:
-     *   - no `sourceVideo` → `/v1/videos/generations` (text/image-to-video)
-     *   - `sourceVideo` + `videoMode:'extend'` (default) → `/v1/videos/extensions`
-     *     — continues from the last frame; takes `duration`, NOT aspect/resolution.
-     *   - `sourceVideo` + `videoMode:'edit'` → `/v1/videos/edits` — prompt + video
-     *     only (no duration/aspect/resolution).
-     *  All three return a `request_id` polled via the same status endpoint. */
-    private buildVideoSubmit;
     getVideoStatus(operationId: string, fetch: EngineFetch): Promise<VideoStatus>;
     downloadVideo(operationId: string, fetch: EngineFetch): Promise<RawMediaResult>;
     cancelVideo(operationId: string, fetch: EngineFetch): Promise<void>;

package/dist/llm/providers/xai/responses.d.ts

@@ -5,8 +5,7 @@
  *  - Reasoning automatic for reasoning models (no effort param needed)
  *  - Encrypted reasoning via include: ["reasoning.encrypted_content"]
  */
-import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
-import type { NormalizedRequest } from '../../types/request';
+import type { ProviderAdapter } from '../../types/provider';
 import type { FileOutput } from '../../types/response';
 import { OpenAIResponsesAdapter } from '../openai/responses';
 export interface XAIResponsesAdapterConfig {
@@ -17,7 +16,10 @@ export declare class XAIResponsesAdapter extends OpenAIResponsesAdapter {
     readonly name: ProviderAdapter['name'];
     constructor(config: XAIResponsesAdapterConfig);
     baseURL(): string;
-    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** Everything this class used to do to `super.buildRequest()` — the max_tokens
+     *  rename, the reasoning strip, the tier remap, the routing passthrough — is the
+     *  `xai` overlay in the shared spec. Naming the flavor IS the override now. */
+    protected readonly wireFlavor: string;
     /** xAI embeds code-execution files inline in the `logs` payload — extend the base
      *  extraction (which handles OpenAI-style annotations / image URLs) with the xAI shape. */
     protected filesFromOutputItem(item: Record<string, unknown>): FileOutput[];

package/dist/llm/response-shape.d.ts

@@ -0,0 +1,96 @@
+/** Runtime shape check — tell me when a provider's response stops looking like the
+ *  one we learned to read.
+ *
+ *  Parsing is the half of the library with the least warning before a failure. A
+ *  request that goes wrong comes back as a 400. A RESPONSE that goes wrong comes
+ *  back as a 200 with a field we do not read: the parse succeeds, the number is
+ *  `undefined`, and the first sign is a cost dashboard that quietly reports zero
+ *  or a tool call that never arrives. `google/generate` shipped for months
+ *  discarding a `responseId` that had been there all along, under a comment saying
+ *  it did not exist.
+ *
+ *  So this compares the body against a description of the shape we understand:
+ *
+ *    unknown path      a field we have never seen. Either the provider added it —
+ *                      possibly the one carrying something we now want — or we are
+ *                      talking to something that is not the API we think.
+ *    missing path      a field present in EVERY recording is absent from this one.
+ *                      That is the shape of a rename, and a rename is what silently
+ *                      turns a token count into `undefined`.
+ *    unknown value     a discriminator (`type`, `role`, `finish_reason`, …) carries
+ *                      a value we do not branch on. A new content-block type is the
+ *                      most expensive kind of drift there is, because the content
+ *                      is simply dropped and nothing errors.
+ *
+ *  OFF by default, and it never changes what is parsed: it only emits `onWarning`.
+ *  A check that could alter a response would be a new way to break one.
+ *
+ *  The descriptions in `response-shapes.json` are DERIVED, not hand-written —
+ *  `scripts/derive-response-shapes.ts` builds them from the recorded corpus, and a
+ *  test asserts every recorded body produces no unknown paths. That is what keeps
+ *  the description honest: it cannot drift from real responses without a test going
+ *  red, and when a provider does add a field, re-recording surfaces it as a
+ *  decision rather than as a silent difference.
+ */
+import type { HookBus } from '../bus/hook-bus';
+import type { SSEEvent } from '../network/types';
+export interface ShapeDecl {
+    /** Every path seen across the recordings for this target. */
+    known: string[];
+    /** Paths present in EVERY recording — absence is worth a warning. */
+    expected: string[];
+    /** Discriminator path → the values we have actually seen. */
+    values?: Record<string, string[]>;
+}
+export interface ShapeSet {
+    /** The non-streaming body. */
+    response?: ShapeDecl;
+    /** One declaration PER SSE event type, keyed by the SSE `event:` name when the
+     *  provider sends one and by the payload's own `type` otherwise.
+     *
+     *  Pooling every event type into one declaration was the first attempt, and it
+     *  cost the missing-field check entirely: `message_start` and
+     *  `content_block_delta` share almost no fields, so the intersection across a
+     *  whole stream came to a single path and nothing could ever be reported
+     *  absent. Per type, "this event always carries usage" becomes a statement
+     *  worth making. */
+    stream?: Record<string, ShapeDecl>;
+}
+/** How an SSE event names its own kind. The SSE `event:` line wins — Anthropic
+ *  routes on it, and its payload `type` merely repeats it — then the payload's
+ *  `type`, then a single bucket for providers that discriminate on neither
+ *  (chat-completions chunks are all one shape). */
+export declare function streamEventKey(event: SSEEvent, data: unknown): string;
+export type ShapeBook = Record<string, ShapeSet>;
+export interface ShapeFindings {
+    unknown: string[];
+    missing: string[];
+    /** `[path, value]` for a discriminator carrying something new. */
+    unknownValues: Array<[string, string]>;
+}
+/** Collect the paths of a value. Array indices collapse to `[]` — otherwise a
+ *  three-element list would describe a different shape than a four-element one. */
+export declare function pathsOf(value: unknown, prefix?: string, out?: Set<string>, depth?: number): Set<string>;
+/** Collect `path → value` for the discriminator keys only. */
+export declare function discriminatorsOf(value: unknown, prefix?: string, out?: Array<[string, string]>, depth?: number): Array<[string, string]>;
+/** Compare one body against a declaration. Pure — the caller decides what to do. */
+export declare function checkShape(body: unknown, decl: ShapeDecl): ShapeFindings;
+/** Per-client checker. Holds what it has already reported, because the alternative
+ *  is the same warning on every request for the rest of the process — which is how
+ *  a diagnostic gets muted by the person reading it. */
+export declare class ResponseShapeChecker {
+    private readonly hooks;
+    private readonly provider;
+    private readonly api;
+    private readonly book;
+    private readonly reported;
+    constructor(hooks: HookBus, provider: string, api: string, book: ShapeBook);
+    /** The declaration for this client, or undefined when nothing was recorded for
+     *  it — in which case the check stays silent rather than calling every field
+     *  unknown. */
+    private get set();
+    checkResponse(body: unknown): void;
+    checkStreamEvent(event: SSEEvent): void;
+    private report;
+    private warn;
+}

package/dist/llm/types/provider.d.ts

@@ -6,6 +6,12 @@ import type { NormalizedRequest } from './request';
 import type { CompletionResponse } from './response';
 import type { StreamEvent } from './stream';
 export type ProviderName = 'anthropic' | 'openai' | 'google' | 'xai' | 'openrouter';
+/** The same five names at runtime. A `"vendor/model"` prefix can only be read as
+ *  a provider if it IS one — OpenRouter's own ids are all `vendor/model`, so
+ *  without this check `openai/gpt-5.4-nano` on OpenRouter parses as the provider
+ *  `openai`, and `qwen/qwen3` parses as a provider named `qwen`. */
+export declare const PROVIDER_NAMES: readonly ["anthropic", "openai", "google", "xai", "openrouter"];
+export declare function isProviderName(value: string): value is ProviderName;
 export type ApiType = 'completions' | 'responses' | 'messages' | 'interactions' | 'generate';
 export interface ProviderConfig {
     provider: ProviderName;
@@ -18,6 +24,11 @@ export interface ProviderHttpRequest {
     /** Override of the default completion path. Used by providers that route
      *  per-API or per-modality. */
     path?: string;
+    /** What the build deliberately left out, and why — a hosted tool this provider
+     *  refuses to run beside the attached content, for instance. The client emits
+     *  each as `onWarning`, because dropping a capability the caller asked for and
+     *  saying nothing is how a missing feature gets mistaken for a working one. */
+    notes?: string[];
 }
 export interface ProviderAdapter {
     readonly name: ProviderName;

package/dist/llm/types/request.d.ts

@@ -4,7 +4,6 @@
  *  and system are fixed at construction. The LLMClient internally builds
  *  this `NormalizedRequest` from (input, options, this.model, this.system). */
 import type { ModerationRequest } from '../moderation/types';
-import type { ModelWire } from '../../catalog/catalog';
 import type { AudioOptions } from './audio';
 import type { Message } from './messages';
 import type { ServiceTier } from './tiers';
@@ -92,11 +91,11 @@ export interface NormalizedRequest {
     serviceTier?: ServiceTier;
     moderation?: ModerationRequest;
     providerOptions?: ProviderOptions;
-    /** Wire traits for THIS model, resolved from the catalog by `LLMClient`.
-     *  Adapters prefer this over parsing the model id. Absent when the engine runs
-     *  without a catalog or the model is not catalogued, in which case adapters
-     *  fall back to the id. */
-    wire?: ModelWire;
+    /** Which wire spec builds this request, from the catalog's `ModelInfo.wireSpec`
+     *  and resolved by `LLMClient`. Absent when the engine runs without a catalog or
+     *  the model is not catalogued, in which case the adapter derives the spec from
+     *  the model id — the same fallback `wire` has. */
+    wireSpec?: string;
     audio?: AudioOptions;
     outputModalities?: Array<'text' | 'audio'>;
     previousResponseId?: string;

package/dist/llm/wire-multipart.d.ts

@@ -0,0 +1,26 @@
+/** Turn a spec's multipart DESCRIPTOR into a real FormData.
+ *
+ *  A spec can say that a request is multipart and which fields it carries, but not
+ *  what the bytes are — those come from a `FileAttachment` the caller holds. So the
+ *  interpreter emits `{ name, kind: 'file' | 'value', value? }` and this fills in
+ *  the one part it cannot: the file itself.
+ *
+ *  Kept out of `src/wire/` deliberately. The wire layer has no outbound imports and
+ *  no notion of an attachment; this is the seam where spec data meets the caller's
+ *  bytes, which makes it llm-layer glue rather than part of the interpreter.
+ */
+import type { MultipartField } from './../wire/interpreter';
+export interface MultipartFile {
+    /** The bytes, already read. */
+    data: Uint8Array;
+    filename: string;
+    mimeType: string;
+}
+/** Build the FormData a multipart spec describes.
+ *
+ *  Field ORDER follows the spec, because multipart is an ordered format and some
+ *  servers care. A `file` field with no file supplied is an error rather than an
+ *  omission: a silently fileless upload would be accepted by the type checker and
+ *  rejected by the provider, which is the exact failure mode the specs exist to
+ *  remove. */
+export declare function toFormData(fields: MultipartField[], file: MultipartFile): FormData;

package/dist/{wire/transforms.d.ts → llm/wire-transforms.d.ts}

@@ -8,14 +8,20 @@
  *  structural message/content transformation, schema-shape rules, and one
  *  variant rule that is arithmetic rather than a pattern.
  */
-import type { Registry } from './interpreter';
+import type { Registry } from '../wire/interpreter';
 /** Adapters whose private message builders we reuse. Instantiated once; the
  *  builders are pure with respect to the request. */
+/** The hand-written adapter methods the specs cannot express as data.
+ *
+ *  All optional: a registry built by ONE adapter to drive its own spec carries only
+ *  its own handle, and each transform below is reached only from that provider's
+ *  spec. Requiring the full set would force every adapter to import every other
+ *  adapter just to build its own request. */
 export interface AdapterHandles {
-    anthropic: any;
-    google: any;
-    openaiResponses: any;
-    openaiCompletions: any;
+    anthropic?: any;
+    google?: any;
+    openaiResponses?: any;
+    openaiCompletions?: any;
     googleInteractions?: any;
     openrouterMedia?: any;
 }

package/dist/plugins/context-measurer/counter/count-api.d.ts

@@ -1,14 +1,14 @@
 /** Count API adapter — exact token counting via provider endpoints. */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
-import type { FetchFn } from '../../../network/types';
+import type { EngineFetch } from '../../../network/types';
 import type { ModelCatalog } from '../../../catalog/catalog';
 /** Anthropic count endpoint: POST /v1/messages/count_tokens */
 export declare class AnthropicCountApi {
     private readonly apiKey;
     private readonly fetchFn;
     private readonly baseURL;
-    constructor(apiKey: string, fetchFn?: FetchFn, baseURL?: string);
+    constructor(apiKey: string, fetchFn: EngineFetch, baseURL?: string);
     countMessages(model: string, messages: Array<{
         role: string;
         content: unknown;
@@ -20,18 +20,52 @@ export declare class GoogleCountApi {
     private readonly apiKey;
     private readonly fetchFn;
     private readonly baseURL;
-    constructor(apiKey: string, fetchFn?: FetchFn, baseURL?: string);
+    constructor(apiKey: string, fetchFn: EngineFetch, baseURL?: string);
     countText(model: string, text: string): Promise<number>;
 }
-/** TokenCounter backed by Anthropic/Google count APIs. Falls back to heuristic
- *  for fast estimates and unknown providers. */
+/** xAI tokenizer: POST /v1/tokenize-text
+ *
+ *  Their own SDK reaches this over gRPC (`xai_api.Tokenize/TokenizeText`), which
+ *  is why it looked for a while like exact counting on xAI would cost a protobuf
+ *  dependency. It does not: the REST host answers the same call with the same
+ *  token list, so this is one more spec-built request and the library stays
+ *  zero-dependency.
+ *
+ *  What it counts is TEXT, not a chat request. Anthropic's and Google's endpoints
+ *  take the message array a completion would send, so their answer matches what
+ *  the completion is billed for; this one tokenizes the string you hand it, so it
+ *  is exact for that string and excludes the framing the chat template adds
+ *  around it. Still the right answer to "how many tokens is this content", and
+ *  vastly better than four-chars-per-token — on one Cyrillic line the heuristic
+ *  says 9 where the tokenizer says 19.
+ *
+ *  The response names the list `token_ids` (the proto calls it `tokens`); the
+ *  count is its length. */
+export declare class XAICountApi {
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly baseURL;
+    constructor(apiKey: string, fetchFn: EngineFetch, baseURL?: string);
+    countText(model: string, text: string): Promise<number>;
+}
+/** TokenCounter backed by Anthropic/Google/xAI count APIs. Falls back to
+ *  heuristic for fast estimates and unknown providers. */
 export declare class CountApiCounter implements TokenCounter {
     private readonly providers;
     private heuristic;
+    private readonly catalog;
     constructor(catalog: ModelCatalog | null, providers?: {
         anthropic?: AnthropicCountApi;
         google?: GoogleCountApi;
+        xai?: XAICountApi;
     });
+    /** The id to SEND. `ctx.model` is our canonical slug — `claude-haiku-4.5` —
+     *  which is not what the provider answers to: its callable id is the dated
+     *  `claude-haiku-4-5-20251001`. The chat path translates through the catalog;
+     *  this one did not, so the moment a model's slug and api id differed the count
+     *  endpoint returned 404. Nothing noticed while the strategy was never
+     *  selected. */
+    private apiModel;
     estimate(text: string, ctx?: TokenCountContext): number;
     estimateMessage(msg: Message, ctx?: TokenCountContext): number;
     measure(text: string, ctx?: TokenCountContext): Promise<number>;

package/dist/plugins/context-measurer/counter/hybrid.d.ts

@@ -2,6 +2,7 @@
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
 import type { ModelCatalog } from '../../../catalog/catalog';
+import type { EngineFetch } from '../../../network/types';
 import type { CalibrationStore } from '../types';
 export interface HybridCounterConfig {
     catalog?: ModelCatalog;
@@ -9,7 +10,14 @@ export interface HybridCounterConfig {
     countApiKeys?: {
         anthropic?: string;
         google?: string;
+        xai?: string;
     };
+    /** Required to use the exact count APIs: they are HTTP calls, and every HTTP
+     *  call in this library goes through the engine's fetch. Without it the exact
+     *  strategies are unavailable and counting falls back to the heuristic — which
+     *  is said out loud rather than done quietly, because a silent downgrade from
+     *  exact to estimated is invisible in the only place it matters: the number. */
+    fetch?: EngineFetch;
 }
 /**
  * HybridTokenCounter routes based on catalog's tokenizer.strategy:
@@ -24,6 +32,8 @@ export declare class HybridTokenCounter implements TokenCounter {
      *  counter. See CONSTITUTION.md standing decisions (2026-08-08). */
     private _tiktoken?;
     private countApi;
+    /** Said once per counter, not once per call. */
+    private warnedNoTiktoken;
     private readonly _config;
     constructor(config: HybridCounterConfig);
     warmCache(): Promise<void>;
@@ -31,6 +41,29 @@ export declare class HybridTokenCounter implements TokenCounter {
     estimateMessage(msg: Message, ctx?: TokenCountContext): number;
     measure(text: string, ctx?: TokenCountContext): Promise<number>;
     measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    /** Run the chosen strategy, falling back to the heuristic if — and ONLY if —
+     *  the optional `tiktoken` peer is not installed.
+     *
+     *  The catalog can name `tiktoken` for a model without the consumer having
+     *  installed it: it is an optional PEER dependency precisely so that most
+     *  people do not carry its 5.6 MB of wasm. Without this, marking OpenAI models
+     *  as exactly-countable would turn a number into a thrown error for everyone
+     *  who did not opt in — and the guide has always promised the opposite
+     *  ("without it everything still works").
+     *
+     *  Only THAT error is caught. A network failure inside the count API, or a
+     *  genuine tokenizer fault, still surfaces: silently answering with an estimate
+     *  when an exact count was asked for and was possible is how a wrong number
+     *  gets believed. */
+    private withoutOptionalPeer;
     learn(input: LearnInput): void;
+    /** Which strategy a context resolves to, without running it.
+     *
+     *  Public because a caller has to be able to ASK. `countTokens()` records a
+     *  zero-cost ledger entry for a count-API call, and it was deciding that from
+     *  the provider and the presence of a key — that is intent, not evidence. It now
+     *  asks what actually ran, so the ledger cannot claim a provider call that never
+     *  left the process. */
+    strategyNameFor(ctx?: TokenCountContext): 'tiktoken' | 'count_api' | 'heuristic';
     private strategyFor;
 }

package/dist/plugins/context-measurer/counter/tiktoken.d.ts

@@ -6,8 +6,15 @@
  */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+/** Marks the one error a caller is allowed to treat as "use something else". */
+export declare const TIKTOKEN_MISSING: unique symbol;
 /** Build the error thrown when the optional peer is missing. Exported for tests; not public API. */
 export declare function tiktokenUnavailableError(cause: unknown): Error;
+/** Is this the "tiktoken is not installed" error, rather than any other failure?
+ *
+ *  Matched on the marker below rather than on the message text, so rewording the
+ *  message cannot silently turn a graceful fallback into a thrown error. */
+export declare function isTiktokenUnavailable(err: unknown): boolean;
 export declare class TiktokenCounter implements TokenCounter {
     private encodings;
     estimate(text: string, ctx?: TokenCountContext): number;