@combycode/llm-sdk 2.2.2 → 3.0.0

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

@@ -1,7 +1,7 @@
 /** LLMClient configuration types. */
 import type { HookBus } from '../bus/hook-bus';
 import type { EngineFetch, EngineFetchStream } from '../network/types';
-import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { ModelCatalog } from '../catalog/catalog';
 import type { RequestContext } from '../types/request-context';
 import type { ApiType, ProviderAdapter, ProviderName } from './types/provider';
 import type { NormalizedRequest } from './types/request';
@@ -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-internal.d.ts

@@ -34,6 +34,17 @@ export declare function extractSystem(messages: Message[]): {
 /** Strip leading/trailing markdown fences and JSON.parse. Exported so AgentLoop
  *  + helper can share the same parsing rules. */
 export declare function parseStructured<T>(text: string): T;
+/** The routing names `buildContext` needs from a client.
+ *
+ *  These were read with `as unknown as { queueName: string }` casts straight into
+ *  LLMClient's privates — which compiles, and silently returns `undefined` the
+ *  day a field is renamed. LLMClient now exposes them deliberately as
+ *  `client.routing`, so a rename is a type error instead. */
+export interface ClientRouting {
+    readonly queueName: string;
+    readonly configName: string;
+    readonly cacheName: string;
+}
 export declare function buildContext(client: LLMClient, options: ExecuteOptions): RequestContext;
 export declare function resolveApi(provider: ProviderName, api?: ApiType | 'auto'): ApiType;
 export declare function resolveAdapter(config: LLMClientConfig, api: ApiType): ProviderAdapter;

package/dist/llm/client.d.ts

@@ -25,6 +25,7 @@ import type { ApiType, ProviderName } from './types/provider';
 import type { CompletionResponse, FileOutput } from './types/response';
 import type { StreamEvent } from './types/stream';
 import type { LLMClientConfig } from './client-config';
+import { type ClientRouting } from './client-internal';
 export declare class LLMClient {
     readonly id: string;
     /** Trace session id (from the engine, or self-minted for a standalone client). */
@@ -37,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;
@@ -44,6 +47,9 @@ export declare class LLMClient {
     private readonly queueName;
     private readonly configName;
     private readonly cacheName;
+    /** The routing names this client was configured with, exposed so context
+     *  building does not have to cast into the privates above. */
+    readonly routing: ClientRouting;
     private readonly cacheKeyFn?;
     private readonly catalog;
     constructor(config: LLMClientConfig);

package/dist/llm/providers/_shared/sse.d.ts

@@ -0,0 +1,19 @@
+/** The one piece of SSE handling every provider genuinely shares.
+ *
+ *  Report 035 proposed a shared "SSE -> StreamEvent parser" because the parsing
+ *  looked duplicated ~5x. Measured, it is not: the six parse bodies (76-149
+ *  lines each) share ZERO runs of three or more identical lines, because they
+ *  decode different wire schemas — Anthropic's `content_block_*` events,
+ *  OpenAI chat's `choices[].delta`, OpenAI Responses' typed events, and Google's
+ *  `candidates[].content.parts`. A "shared" parser would be a switch on provider
+ *  wearing a common signature.
+ *
+ *  What IS shared is exactly this line, repeated six times. Naming it gives the
+ *  three language ports one primitive to agree on instead of six independent
+ *  decisions, and one place to harden if malformed frames ever need handling
+ *  (today a bad frame throws out of the parser, which is the existing
+ *  behaviour and deliberately unchanged here).
+ */
+import type { SSEEvent } from '../../../network/types';
+/** Decode an SSE frame's `data` payload as a JSON object. */
+export declare function sseJson(event: SSEEvent): Record<string, unknown>;

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,8 +1,23 @@
 /** 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.
+ *
+ *  Three forms reach this, and only two used to work:
+ *
+ *    https://.../v1beta/files/abc  the `uri` this adapter hands back from
+ *                                 upload() and list() — matched on `/files/`
+ *    abc                          a bare name — passed through
+ *    files/abc                    Google's CANONICAL resource name, the `name`
+ *                                 field its own API returns
+ *
+ *  The third fell through the `/files/` test (no leading slash) and produced
+ *  `/v1beta/files/files/abc` — a 404. It never broke this library's own
+ *  round-trip, because upload() and list() return the `uri`; it broke the
+ *  moment a caller passed the id Google itself gave them. */
+export declare function googleFileName(remoteId: string): string;
 export interface GoogleFileAdapterConfig {
     apiKey: string;
     baseURL?: string;
@@ -15,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

@@ -1,6 +1,6 @@
 /** Google media adapter — Imagen (:predict) + Veo (:predictLongRunning).
  *  All HTTP calls go through an injected EngineFetch (NetworkEngine queue). */
-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 GoogleMediaAdapterConfig {
     apiKey: string;
@@ -12,14 +12,55 @@ 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;
+    /** 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>;
     /** Image-to-image edit: gemini generateContent with the source image as an
      *  extra inline/file part next to the instruction. */
     editImage(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
-    /** Shared inline-media path: POST :generateContent and collect inlineData
-     *  parts + the reported token usage (token-priced media). */
-    private generateContentMedia;
+    /** Collect inlineData parts + reported usage from a `:generateContent`
+     *  response. The request half is `buildGenerateContentRequest`; keeping the two
+     *  apart is what lets a request be asserted without performing it. */
+    private parseGenerateContent;
     submitVideo(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
     getVideoStatus(operationId: string, fetch: EngineFetch): Promise<VideoStatus>;
     downloadVideo(operationId: string, fetch: EngineFetch): Promise<RawMediaResult>;

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

@@ -13,8 +13,8 @@
  *
  *  Gemini Live models are audio-native: with responseModalities ['AUDIO'] the
  *  parts carry inlineData audio, not text. */
-import type { EngineConnect } from '../../../network/types';
-import type { RealtimeProviderAdapter, RealtimeSession, RealtimeSessionConfig } from '../../realtime/types';
+import type { EngineConnect, WsRequest } from '../../../network/types';
+import type { RealtimeInput, RealtimeProviderAdapter, RealtimeSession, RealtimeSessionConfig } from '../../realtime/types';
 export interface GoogleRealtimeAdapterConfig {
     apiKey: string;
     baseURL?: string;
@@ -23,5 +23,18 @@ export declare class GoogleRealtimeAdapter implements RealtimeProviderAdapter {
     private readonly apiKey;
     private readonly base;
     constructor(config: GoogleRealtimeAdapterConfig);
+    /** The WebSocket descriptor. Separated from `connect` so it can be asserted
+     *  without opening a socket. Gemini authenticates with a query-string key and
+     *  does NOT name the model in the URL — that goes in the setup frame. */
+    buildConnectRequest(config: RealtimeSessionConfig): WsRequest;
     connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
 }
+/** The handshake frame. Pure: a function of the session config, so it can be
+ *  asserted without opening a socket. Gemini Live names the model HERE rather
+ *  than in the URL, which is the opposite of OpenAI. */
+export declare function buildGoogleSetupFrame(config: RealtimeSessionConfig): Record<string, unknown>;
+/** The frames for one turn. Gemini carries turn completion as a FIELD, where
+ *  OpenAI signals it by sending a second frame. */
+export declare function buildGoogleTurnFrames(input: RealtimeInput, opts?: {
+    turnComplete?: boolean;
+}): Array<Record<string, unknown>>;

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>;
 }