@combycode/llm-sdk 2.2.2 → 3.0.0

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

@@ -1,7 +1,7 @@
 /** OpenAI media adapter — image generation (/v1/images/generations) and TTS
  *  (/v1/audio/speech). All HTTP calls flow through an injected EngineFetch
  *  so they share the NetworkEngine queue, rate-limits, retry, and hooks. */
-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 OpenAIMediaAdapterConfig {
     apiKey: string;
@@ -13,7 +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

@@ -10,8 +10,8 @@
  *        response.output_audio.delta  → { audio, base64 delta }
  *        response.done                → turn complete
  *        error                        → error */
-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 OpenAIRealtimeAdapterConfig {
     apiKey: string;
     baseURL?: string;
@@ -20,5 +20,21 @@ export declare class OpenAIRealtimeAdapter implements RealtimeProviderAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAIRealtimeAdapterConfig);
+    /** The WebSocket descriptor. Separated from `connect` so it can be asserted
+     *  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;
 }
+/** The handshake frame, sent once the socket opens. */
+export declare function buildOpenAISessionUpdate(config: Pick<RealtimeSessionConfig, 'modalities' | 'instructions' | 'voice'>): Record<string, unknown>;
+/** The frames for one turn. `response.create` is what asks the model to reply,
+ *  so `turnComplete: false` withholds it and the turn stays open — where Gemini
+ *  carries the same meaning as a field on its single frame. */
+export declare function buildOpenAITurnFrames(input: RealtimeInput, opts?: {
+    turnComplete?: boolean;
+}): Array<Record<string, unknown>>;

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[];

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/server-state.d.ts

@@ -13,7 +13,7 @@
  *    - it's within the retention TTL (catalog duration),
  *    - the model matches, OR the provider is not model-bound (catalog).
  *  Otherwise we fall back to resending full history (always correct). */
-import type { ModelCatalog } from '../plugins/model-catalog/catalog';
+import type { ModelCatalog } from '../catalog/catalog';
 import type { Message } from './types/messages';
 import type { ProviderName } from './types/provider';
 export interface ServerStateDecision {

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

@@ -3,7 +3,7 @@ import type { ConversationHistory } from '../../agent/history';
 import type { RequestContext } from '../../types/request-context';
 import type { ModerationRequest } from '../moderation/types';
 import type { AudioOptions } from './audio';
-import type { CacheConfig, ThinkingConfig } from './request';
+import type { CacheConfig, ProviderOptions, ThinkingConfig } from './request';
 import type { ServiceTier } from './tiers';
 import type { Tool, ToolChoice } from './tools';
 export interface ExecuteOptions {
@@ -65,7 +65,7 @@ export interface ExecuteOptions {
      *  OpenAI runs it natively; other providers are emulated via OpenAI's
      *  moderations endpoint. See ModerationRequest. */
     moderation?: ModerationRequest;
-    providerOptions?: Record<string, unknown>;
+    providerOptions?: ProviderOptions;
     previousResponseId?: string;
     /** Server-state optimization: when the prior assistant turn carries a usable
      *  server id (same provider, within TTL, model ok), send the id + only the new

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;