@combycode/llm-sdk 2.3.0 → 3.1.0

package/dist/llm/client-config.d.ts

@@ -34,4 +34,12 @@ export interface LLMClientConfig {
      *  createLLM supplies `engine.catalog`. An empty catalog still yields correct
      *  provider-level defaults, so this is optional. */
     catalog?: ModelCatalog;
+    /** Warn when a provider's response stops looking like the one we learned to
+     *  read — a field we have never seen, a field that was always there and is now
+     *  absent, or a discriminator carrying a value nothing branches on.
+     *
+     *  OFF by default and never changes what is parsed: it only emits `onWarning`.
+     *  `createEngine({ checkResponseShapes: true })` turns it on for every client
+     *  the engine builds. See `src/llm/response-shape.ts`. */
+    checkResponseShapes?: boolean;
 }

package/dist/llm/client.d.ts

@@ -38,6 +38,8 @@ export declare class LLMClient {
     readonly mode: 'foreground' | 'background';
     readonly batchable: boolean;
     private readonly adapter;
+    /** Present only when the caller asked for the shape check. */
+    private readonly shapeChecker?;
     private readonly apiKey;
     private readonly fetchFn;
     private readonly fetchStreamFn;
@@ -83,6 +85,9 @@ export declare class LLMClient {
      *  files piped straight to a file / GridFS / HTTP response without buffering. */
     streamFile(file: FileOutput): Promise<FileStream>;
     /** Submit a request. Returns the parsed CompletionResponse. */
+    /** Anything the spec left out on purpose reaches the caller as a warning.
+     *  Said once per request; the build already de-duplicates within one. */
+    private reportBuildNotes;
     complete(input: string | ContentPart[] | Message[], options?: ExecuteOptions): Promise<CompletionResponse>;
     /** Run `complete` with a JSON Schema enforced via `structured`. Strips any
      *  leading/trailing markdown fences from the model reply, then JSON.parses

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

@@ -1,6 +1,6 @@
 /** Anthropic batch adapter — POST /v1/messages/batches with inline requests.
  *  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 AnthropicBatchAdapterConfig {
     apiKey: string;
@@ -11,7 +11,18 @@ export declare class AnthropicBatchAdapter implements BatchProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: AnthropicBatchAdapterConfig);
-    private authHeaders;
+    /** Batch rules need no adapter handles: the requests are mapped by the spec. */
+    private readonly wireRegistry;
+    /** Build one batch request from its spec, then add the engine metadata.
+     *  Every batch call is routed under the `batch` model name for queueing. */
+    private fromSpec;
+    buildSubmitRequest(requests: BatchRequest[]): HttpRequest;
+    buildStatusRequest(batchId: string): HttpRequest;
+    /** Results stream back as JSONL, so this one decodes as TEXT. Forcing `json`
+     *  here would have broken every batch read — caught by the frozen corpus, not
+     *  by any type. */
+    buildResultsRequest(batchId: string): HttpRequest;
+    buildCancelRequest(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/anthropic/constants.d.ts

@@ -1,45 +1,10 @@
-/** Anthropic provider constants. */
+/** Anthropic provider constants.
+ *
+ *  The thinking-shape and top_k band helpers that used to live here are gone: that
+ *  knowledge is now `src/wire/pins/anthropic.messages.json`, and the token budgets
+ *  are a `$table` inside the chain specs. Both were version arithmetic in
+ *  TypeScript, which the Python and Rust ports would have had to re-implement and
+ *  keep in step - and one copy drifting is exactly how 2.2.1 shipped the wrong
+ *  thinking shape. */
 /** The Anthropic API version header sent on every request. */
 export declare const ANTHROPIC_API_VERSION = "2023-06-01";
-/**
- * Token budgets for Anthropic extended thinking by effort level.
- * Used to set budget_tokens in the `thinking` request param.
- */
-export declare const ANTHROPIC_THINKING_BUDGETS: Record<string, number>;
-/**
- * Budget applied when no effort level is specified or when the level is
- * unrecognised.
- */
-export declare const DEFAULT_ANTHROPIC_THINKING_BUDGET = 2048;
-/**
- * The version at which `thinking: {type:'adaptive'}` takes over from
- * `{type:'enabled', budget_tokens}`.
- *
- * There is no shape that works everywhere, and the direction reversed under us. This
- * adapter used to send the budgeted form to every model, on the reasoning that it was the
- * universally accepted one — true when it was written. Anthropic then REMOVED
- * `budget_tokens` on 4.7 and later: Sonnet 5, Opus 5/4.8/4.7 and Fable 5 reject it with a
- * 400 ("thinking.type.enabled is not supported for this model"). Meanwhile the older half
- * — Haiku 4.5, Sonnet 4.5, Opus 4.x — has no `adaptive` at all and still requires the
- * budget. So the shape must be chosen per model.
- *
- * 4.6 is the boundary: it accepts both and prefers `adaptive`, everything above requires
- * `adaptive`, everything below requires the budget.
- */
-export declare const ANTHROPIC_ADAPTIVE_THINKING_MIN: {
-    readonly major: 4;
-    readonly minor: 6;
-};
-/**
- * Pick the `thinking` shape for a model id.
- *
- * Parsed from the id rather than read from the catalog on purpose: the catalog is optional
- * (an engine can run with none), `buildRequest` has no access to it, and its per-model
- * `reasoning` block does not currently distinguish the two shapes anyway.
- *
- * An unrecognised id gets `adaptive`, because `budget_tokens` is the shape being retired —
- * an id we do not recognise is far likelier to be newer than us than older.
- */
-export declare function anthropicThinkingShape(model: string): 'adaptive' | 'budgeted';
-/** True when this Anthropic model still accepts `top_k` (see ANTHROPIC_TOP_K_MODELS). */
-export declare function anthropicAcceptsTopK(model: string): boolean;

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

@@ -1,6 +1,6 @@
 /** Anthropic file adapter — POST /v1/files (beta).
  *  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 AnthropicFileAdapterConfig {
@@ -15,7 +15,18 @@ export declare class AnthropicFileAdapter implements FileProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: AnthropicFileAdapterConfig);
-    private authHeaders;
+    /** 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): HttpRequest;
+    buildDeleteRequest(remoteId: string): HttpRequest;
+    buildGetInfoRequest(remoteId: string): HttpRequest;
+    buildListRequest(): 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/anthropic/messages.d.ts

@@ -4,6 +4,7 @@
  *  of CompletionRequest (same shape, renamed for v2 to reflect it's the
  *  internal normalized form LLMClient hands to the adapter). */
 import type { SSEEvent } from '../../../network/types';
+import type { ContentPart } from '../../types/messages';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
 import { type CompletionResponse } from '../../types/response';
@@ -19,10 +20,26 @@ export declare class AnthropicAdapter implements ProviderAdapter {
     constructor(config: AnthropicAdapterConfig);
     authHeaders(): Record<string, string>;
     baseURL(): string;
+    /** Named code the spec cannot express as data — message and content assembly.
+     *  Built once, carrying only this adapter, since only Anthropic rules run. */
+    private readonly wireRegistry;
     completionPath(): string;
+    /** The spec that builds this model's request.
+     *
+     *  The catalog pin decides when there is one. Without it — an engine running
+     *  with no catalog, or a model released after this build — the band comes from
+     *  the pin TABLE, which is data (`src/wire/pins/`) rather than version
+     *  arithmetic in TypeScript, so the Python and Rust ports derive the same node
+     *  from the same file instead of each re-implementing it. */
+    private specIdFor;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
     enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
-    private buildMessage;
+    /** Reached through the wire registry while building this adapter's own request. */
+    buildMessage(msg: {
+        role: string;
+        content: string | ContentPart[];
+        cache?: boolean;
+    }, _req: NormalizedRequest, forceCache?: boolean): Record<string, unknown>;
     private buildContentPart;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];

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

@@ -1,6 +1,6 @@
 /** Google batch adapter — inline batchGenerateContent.
  *  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 GoogleBatchAdapterConfig {
     apiKey: string;
@@ -13,6 +13,19 @@ export declare class GoogleBatchAdapter implements BatchProviderAdapter {
     private readonly model;
     private readonly baseURL;
     constructor(config: GoogleBatchAdapterConfig);
+    /** 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;
+    buildSubmitRequest(requests: BatchRequest[]): HttpRequest;
+    buildStatusRequest(batchId: string): HttpRequest;
+    buildCancelRequest(batchId: string): HttpRequest;
+    /** Google returns results inline on the batch resource, so this is the same
+     *  wire as getStatus - two operations that happen to share one request. */
+    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/google/constants.d.ts

@@ -1,18 +1,9 @@
-/** Google provider constants. */
-/**
- * Map from unified thinking effort levels to Gemini `thinkingLevel` enum strings.
- * `thinkingLevel` is the Gemini 3.x thinking control (LOW/HIGH).
- */
-export declare const GOOGLE_THINKING_LEVELS: Record<string, string>;
-/**
- * Map from unified thinking effort to a Gemini `thinkingBudget` (token count).
- * Gemini **2.5** models only accept a token budget — they 400 on `thinkingLevel`
- * ("Thinking level is not supported for this model", live-verified 2026-07-16).
- * Values sit inside the 2.5 range (flash/flash-lite cap ~24576, pro ~32768).
- */
-export declare const GOOGLE_THINKING_BUDGETS: Record<string, number>;
-/** Gemini 2.5 series uses `thinkingBudget`; 3.x+ uses `thinkingLevel`. */
-export declare function googleUsesThinkingBudget(model: string): boolean;
+/** Google provider constants.
+ *
+ *  The thinking-control tables and the 2.5-vs-3.x band test have moved into data:
+ *  the effort maps are `$table`s in the chain specs, and the band is
+ *  `src/wire/pins/google.generate.json`. Only the Interactions map remains here,
+ *  because its lowercase enum is read by code the specs do not own. */
 /**
  * Effort → Interactions `thinking_level`. The Interactions API uses **lowercase**
  * values (`minimal`/`low`/`medium`/`high`) — distinct from generateContent's

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

@@ -1,6 +1,6 @@
 /** Google embeddings adapter — POST /v1beta/models/{model}:embedContent.
  *  One call per input text (batch via a simple loop). */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { EmbedRequest, EmbedResult, EmbeddingProviderAdapter } from '../../../plugins/embeddings/types';
 export interface GoogleEmbeddingAdapterConfig {
     apiKey: string;
@@ -11,5 +11,12 @@ export declare class GoogleEmbeddingAdapter implements EmbeddingProviderAdapter
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: GoogleEmbeddingAdapterConfig);
+    /** One request, for ONE input text.
+     *
+     *  Google embeds a single text per call, so `embed` loops and this builds one
+     *  iteration. The spec's input context is `{ model, text }` accordingly. */
+    buildEmbedRequest(req: EmbedRequest, text: string): HttpRequest;
+    /** Named code the spec cannot express as data — the models/ path prefix. */
+    private readonly wireRegistry;
     embed(req: EmbedRequest, fetch: EngineFetch): Promise<EmbedResult>;
 }

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

@@ -1,6 +1,6 @@
 /** Google file adapter — resumable upload to Files API. 48h auto-delete.
  *  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';
 /** Reduce any form of Google file id to the bare name the REST path wants.
@@ -30,6 +30,24 @@ export declare class GoogleFileAdapter implements FileProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: GoogleFileAdapterConfig);
+    /** 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;
+    /** Step ONE of the resumable upload. The second call goes to a URL the server
+     *  returns in a response header, so no spec can describe it — it stays here. */
+    buildStartUploadRequest(file: FileAttachment, byteLength: number): HttpRequest;
+    /** Step TWO of the resumable upload. The URL came back in a response header, so
+     *  it is an INPUT to the spec rather than something the spec can build - the same
+     *  way batchId is. */
+    buildFinishUploadRequest(uploadUrl: string, file: FileAttachment, data: Uint8Array): HttpRequest;
+    buildDeleteRequest(remoteId: string): HttpRequest;
+    buildGetInfoRequest(remoteId: string): HttpRequest;
+    buildListRequest(): 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/google/generate.d.ts

@@ -1,5 +1,6 @@
 /** Google Gemini provider adapter (generateContent API). */
 import type { SSEEvent } from '../../../network/types';
+import type { ContentPart } from '../../types/messages';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
 import { type CompletionResponse } from '../../types/response';
@@ -16,11 +17,24 @@ export declare class GoogleAdapter implements ProviderAdapter {
     authHeaders(): Record<string, string>;
     baseURL(): string;
     completionPath(): string;
+    /** Named code the spec cannot express as data — content assembly. */
+    private readonly wireRegistry;
+    /** The spec that builds this model's request.
+     *
+     *  Two nodes, keyed on the one thing that differs on the wire: 2.5 takes a token
+     *  `thinkingBudget` and 400s on `thinkingLevel`, 3.x takes the level. Catalog pin
+     *  first, then the pin TABLE — data rather than a regex in TypeScript, so the
+     *  ports read the same rule. */
+    private specIdFor;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
     enableStreaming(providerReq: ProviderHttpRequest, req: NormalizedRequest): void;
     /** Map tool call IDs to function names (Google needs name in functionResponse) */
     private toolCallNames;
-    private buildContent;
+    /** Reached through the wire registry while building this adapter's own request. */
+    buildContent(msg: {
+        role: string;
+        content: string | ContentPart[];
+    }): Record<string, unknown>;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
     /** Stateful — Google splits the code-execution marker (`executableCode` /

package/dist/llm/providers/google/interactions.d.ts

@@ -3,6 +3,7 @@
  *  Modern API: input, system_instruction, outputs (plural), function_result,
  *  previous_interaction_id for stateful, 72h retention. */
 import type { SSEEvent } from '../../../network/types';
+import type { Message } from '../../types/messages';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
 import { type CompletionResponse } from '../../types/response';
@@ -19,8 +20,11 @@ export declare class GoogleInteractionsAdapter implements ProviderAdapter {
     authHeaders(): Record<string, string>;
     baseURL(): string;
     completionPath(): string;
+    /** Named code the spec cannot express as data — input-item assembly. */
+    private readonly wireRegistry;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
-    private buildInputItems;
+    /** Reached through the wire registry while building the request. */
+    buildInputItems(msg: Message): unknown[];
     /** Track tool call IDs → names for function_result */
     private toolCallNames;
     enableStreaming(providerReq: ProviderHttpRequest): void;

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

@@ -12,22 +12,45 @@ export declare class GoogleMediaAdapter implements MediaProviderAdapter {
     private readonly baseURL;
     constructor(config: GoogleMediaAdapterConfig);
     capabilities(): MediaCapabilities;
+    /** Named code the specs cannot express as data — image-source normalisation. */
+    private readonly wireRegistry;
+    /** Build one media request from its spec, then add the engine metadata.
+     *
+     *  `provider`, `model` and `responseType` are engine concerns, not wire: nothing
+     *  a provider sees, so the specs do not model them. Every Google media response
+     *  is JSON, including Veo's operation handle and the base64 inline data. */
+    /** Build one media request from its spec, then add the engine metadata.
+     *
+     *  `bodyKind: none` arrives as `noBody`; the engine wants the field absent. */
+    private fromSpec;
+    /** Veo returns a long-running operation; these poll and cancel it. */
+    buildOperationStatusRequest(operationId: string): HttpRequest;
+    buildOperationCancelRequest(operationId: string): HttpRequest;
+    /** Google appends the key to the download URI too, which is why fetching the
+     *  generated bytes is a spec rather than a bare GET. */
+    buildDownloadRequest(downloadUrl: string): HttpRequest;
+    /** Imagen image generation: the Vertex-style `:predict` envelope. */
     /** Imagen image generation: the Vertex-style `:predict` envelope. */
     buildImagenRequest(req: ImageGenRequest, model?: string): HttpRequest;
     /** The inline-media path shared by gemini image generation, editing and TTS. */
     buildGenerateContentRequest(model: string, text: string, generationConfig: Record<string, unknown>, extraParts?: Array<Record<string, unknown>>): HttpRequest;
     /** Veo video submission — a long-running operation, hence the endpoint. */
+    /** Veo video submission — a long-running operation, hence the endpoint. */
     buildVideoRequest(req: VideoGenRequest, model?: string): HttpRequest;
-    /** `generationConfig` for the gemini image paths — generation and editing take
-     *  the same one. */
-    private imageGenerationConfig;
     /** The complete image request, whichever of the two Google image paths applies:
      *  Imagen models use `:predict`, gemini-* models generate inline via
      *  `:generateContent` steered by responseModalities. */
+    /** The complete image request, whichever of the two Google image paths applies.
+     *
+     *  Imagen models use `:predict`; gemini-* models generate inline via
+     *  `:generateContent` steered by responseModalities. Different endpoint, body and
+     *  response — the fork is a genuine wire difference, not a preference. */
     buildImageRequest(req: ImageGenRequest, model?: string): HttpRequest;
     /** Gemini TTS: the same inline path with an AUDIO modality and a speechConfig. */
+    /** Gemini TTS: the inline path with an AUDIO modality and a speechConfig. */
     buildAudioRequest(req: AudioGenRequest, model?: string): HttpRequest;
     /** Image-to-image edit: image generation plus the source image as a second part. */
+    /** Image-to-image edit: image generation plus the source image as a second part. */
     buildEditImageRequest(req: ImageEditRequest, model?: string): HttpRequest;
     generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;

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

@@ -1,6 +1,6 @@
 /** OpenAI batch adapter — upload JSONL file, create batch, poll, download 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 OpenAIBatchAdapterConfig {
     apiKey: string;
@@ -11,7 +11,24 @@ export declare class OpenAIBatchAdapter implements BatchProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAIBatchAdapterConfig);
-    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;
+    /** The FIRST call of submit: the requests go up as a JSONL file. The spec names
+     *  the multipart fields; the bytes are the serialised batch. */
+    buildUploadJsonlRequest(jsonl: string): HttpRequest;
+    /** The SECOND call of submit: the JSONL is uploaded first, then the batch is
+     *  created referencing that file id. */
+    buildCreateRequest(fileId: string): HttpRequest;
+    buildStatusRequest(batchId: string): HttpRequest;
+    buildCancelRequest(batchId: string): HttpRequest;
+    /** The SECOND call of the results flow: the output file is JSONL, so it decodes
+     *  as text. The first call is buildStatusRequest, which yields the file id. */
+    buildResultsFileRequest(fileId: 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/openai/completions.d.ts

@@ -1,5 +1,7 @@
 /** OpenAI provider adapter (Chat Completions API). */
 import type { SSEEvent } from '../../../network/types';
+import type { Registry } from '../../../wire/interpreter';
+import type { ContentPart } from '../../types/messages';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
 import { type CompletionResponse } from '../../types/response';
@@ -22,6 +24,12 @@ export declare class OpenAIAdapter implements ProviderAdapter {
     authHeaders(): Record<string, string>;
     baseURL(): string;
     completionPath(): string;
+    /** Named code the spec cannot express as data — message/input assembly. Carries
+     *  `this`, so a subclass drives the same rules with its own overrides. */
+    protected readonly wireRegistry: Registry;
+    /** Which flavor overlay patches the shared spec. Subclasses for
+     *  OpenAI-compatible backends override this and nothing else. */
+    protected readonly wireFlavor: string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
     /** One universal message can become SEVERAL chat-completions messages.
      *
@@ -31,7 +39,11 @@ export declare class OpenAIAdapter implements ProviderAdapter {
      *  the rest unanswered and the provider rejected the whole request with
      *  "No tool output found for function call <id>" — so parallel tools were broken on
      *  every chat-completions backend. */
-    private buildMessages;
+    /** Reached through the wire registry while building the request. */
+    buildMessages(msg: {
+        role: string;
+        content: string | ContentPart[];
+    }): Record<string, unknown>[];
     private buildMessage;
     enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;

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

@@ -1,6 +1,7 @@
 /** OpenAI embeddings adapter — POST /v1/embeddings. Also the base for the
  *  OpenAI-compatible OpenRouter adapter. */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
+import type { Registry } from '../../../wire/interpreter';
 import type { EmbedRequest, EmbedResult, EmbeddingProviderAdapter } from '../../../plugins/embeddings/types';
 export interface OpenAIEmbeddingAdapterConfig {
     apiKey: string;
@@ -11,6 +12,17 @@ export declare class OpenAIEmbeddingAdapter implements EmbeddingProviderAdapter
     protected readonly apiKey: string;
     protected readonly _baseURL: string;
     constructor(config: OpenAIEmbeddingAdapterConfig);
+    /** Named code the spec cannot express as data — the array coercion. */
+    protected readonly wireRegistry: Registry;
     protected embeddingsPath(): string;
+    /** Which spec builds the request. OpenRouter is the same wire on a different
+     *  host and path, expressed as a one-line override of this spec. */
+    protected specId(): string;
+    /** The request, built and inspectable without performing it.
+     *
+     *  `input` is always an array on the wire even when the caller passes one
+     *  string, which is the sort of rule that belongs in data rather than in a
+     *  ternary nobody re-reads. */
+    buildEmbedRequest(req: EmbedRequest): HttpRequest;
     embed(req: EmbedRequest, fetch: EngineFetch): Promise<EmbedResult>;
 }

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

@@ -1,6 +1,6 @@
 /** OpenAI file adapter — POST /v1/files.
  *  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 OpenAIFileAdapterConfig {
@@ -15,7 +15,18 @@ export declare class OpenAIFileAdapter implements FileProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAIFileAdapterConfig);
-    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/openai/media.d.ts

@@ -13,16 +13,36 @@ export declare class OpenAIMediaAdapter implements MediaProviderAdapter {
     private readonly baseURL;
     constructor(config: OpenAIMediaAdapterConfig);
     capabilities(): MediaCapabilities;
-    private authHeaders;
+    /** Named code the specs cannot express as data — image-source normalisation. */
+    private readonly wireRegistry;
+    /** Build one media request from its spec, then add the engine metadata.
+     *
+     *  `provider`, `model` and `responseType` are NOT wire: the NetworkEngine routes
+     *  and decodes with them and no provider ever sees them, so the specs do not
+     *  model them and this layer keeps supplying them. */
+    private fromSpec;
     /** Text-to-image. */
+    /** Text-to-image.
+     *
+     *  The spec forks by family, and the fork is real: gpt-image-1 always returns
+     *  b64_json and REJECTS `response_format`, while dall-e-3 / dall-e-2 still
+     *  require it. */
     buildGenerateImageRequest(req: ImageGenRequest, model?: string): HttpRequest;
     /** Image-to-image edit. Generation's field set minus `style`, plus the source
      *  image and an optional mask. */
+    /** Image-to-image edit. */
     buildEditImageRequest(req: ImageEditRequest, model?: string): HttpRequest;
     /** TTS. `responseType` is arraybuffer because the response is audio bytes. */
+    /** TTS. `responseType` is arraybuffer because the response is audio bytes —
+     *  transport decoding, which is the engine's business rather than the wire's. */
     buildAudioRequest(req: AudioGenRequest, model: string): HttpRequest;
     /** Sora video submission. `seconds` goes on the wire as a string. */
+    /** Sora video submission. */
     buildVideoRequest(req: VideoGenRequest, model?: string): HttpRequest;
+    /** Poll a Sora job. */
+    buildVideoStatusRequest(videoId: string): HttpRequest;
+    /** Download the finished video: bytes, hence arraybuffer. */
+    buildVideoContentRequest(videoId: string): HttpRequest;
     generateImage(req: ImageGenRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
     /** Parse `/v1/images/{generations,edits}` response → RawMediaResult[], with
      *  the request-level usage attached to the first item (billed once). */

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

@@ -2,7 +2,7 @@
  *  Supports text and image+text content-part input as described in
  *  https://platform.openai.com/docs/api-reference/moderations/create
  *  All HTTP flows through the injected EngineFetch. */
-import type { EngineFetch } from '../../../network/types';
+import type { EngineFetch, HttpRequest } from '../../../network/types';
 import type { ModerationContentPart, ModerationResult } from '../../../helpers/moderate-types';
 export interface OpenAIModerationAdapterConfig {
     apiKey: string;
@@ -15,5 +15,15 @@ export declare class OpenAIModerationAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAIModerationAdapterConfig);
+    /** Named code these specs need. */
+    private readonly wireRegistry;
+    /** Build one request from its spec, then add the engine metadata.
+     *
+     *  `bodyKind: none` arrives as `noBody` and `raw` as `rawBody`; the engine wants
+     *  the body field absent in the first case and the caller's bytes in the second. */
+    private fromSpec;
+    /** Report-only classification. `input` reaches the wire untouched: string,
+     *  array of strings, or content parts are all accepted. */
+    buildModerateRequest(input: string | string[] | ModerationContentPart | ModerationContentPart[], model: string): HttpRequest;
     moderate(input: string | string[] | ModerationContentPart | ModerationContentPart[], model: string, fetch: EngineFetch): Promise<ModerationResult[]>;
 }

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

@@ -24,6 +24,9 @@ export declare class OpenAIRealtimeAdapter implements RealtimeProviderAdapter {
      *  without opening a socket. Note the auth: OpenAI carries the key in a
      *  SUBPROTOCOL, not a header or query param, because browsers cannot set
      *  WebSocket headers. */
+    /** The WebSocket descriptor. Note the auth: OpenAI carries the key in a
+     *  SUBPROTOCOL, not a header or query param, because browsers cannot set
+     *  WebSocket headers — which is why the spec models `protocols` at all. */
     buildConnectRequest(config: RealtimeSessionConfig): WsRequest;
     connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
 }

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

@@ -3,7 +3,8 @@
  *  Modern API: input (not messages), instructions (not system role),
  *  output items (not choices), function_call/function_call_output for tools. */
 import type { SSEEvent } from '../../../network/types';
-import type { AssistantPhase } from '../../types/messages';
+import type { AssistantPhase, Message } from '../../types/messages';
+import type { Registry } from '../../../wire/interpreter';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
 import { type CompletionResponse, type FileOutput, type Usage } from '../../types/response';
@@ -20,10 +21,17 @@ export declare class OpenAIResponsesAdapter implements ProviderAdapter {
     authHeaders(): Record<string, string>;
     baseURL(): string;
     completionPath(): string;
+    /** Named code the spec cannot express as data — message/input assembly. Carries
+     *  `this`, so a subclass drives the same rules with its own overrides. */
+    protected readonly wireRegistry: Registry;
+    /** Which flavor overlay patches the shared spec. Subclasses for
+     *  OpenAI-compatible backends override this and nothing else. */
+    protected readonly wireFlavor: string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
     /** Convert a universal Message to Responses API input items.
      *  `toolNames` is threaded across messages so a tool result can name its originating call. */
-    private buildInputItems;
+    /** Reached through the wire registry while building the request. */
+    buildInputItems(msg: Message, toolNames?: Map<string, string>): unknown[];
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent, phaseByItem?: Map<string, AssistantPhase>): StreamEvent[];