@combycode/llm-sdk 1.0.0-rc.0

package/dist/llm/audio/voices.d.ts

@@ -0,0 +1,7 @@
+/** Hybrid voice resolution (A3): a small per-provider alias table maps a unified
+ *  alias to that provider's voice id; any unrecognized string passes through
+ *  unchanged, so raw provider voice ids always work. */
+export declare const VOICE_ALIASES_LIST: readonly ["neutral", "warm", "bright", "deep"];
+export type VoiceAlias = (typeof VOICE_ALIASES_LIST)[number];
+/** Map an alias to the provider's voice id, else return the input unchanged. */
+export declare function resolveVoice(provider: string, voice: string | undefined): string | undefined;

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

@@ -0,0 +1,37 @@
+/** 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 { RequestContext } from '../types/request-context';
+import type { ApiType, ProviderAdapter, ProviderName } from './types/provider';
+import type { NormalizedRequest } from './types/request';
+/** Function that builds a ProviderAdapter for a (provider, apiKey, api, baseURL). */
+export type AdapterFactory = (provider: ProviderName, apiKey: string, api: ApiType, baseURL?: string) => ProviderAdapter;
+export interface LLMClientConfig {
+    provider: ProviderName;
+    model: string;
+    apiKey: string;
+    system?: string;
+    baseURL?: string;
+    /** Trace session id. createLLM passes `engine.sessionId`; a standalone client
+     *  mints its own. Flows onto every RequestContext built by this client. */
+    sessionId?: string;
+    hooks?: HookBus;
+    fetch?: EngineFetch;
+    fetchStream?: EngineFetchStream;
+    /** Provider adapter factory. createLLM supplies a default;
+     *  here you can also pass a pre-built adapter or a custom factory for tests. */
+    adapter?: ProviderAdapter | AdapterFactory;
+    queueName?: string;
+    configName?: string;
+    cacheName?: string;
+    cacheKeyFn?: (req: NormalizedRequest, ctx: RequestContext) => string;
+    api?: ApiType | 'auto';
+    mode?: 'foreground' | 'background';
+    batchable?: boolean;
+    priority?: number;
+    /** Model catalog — source of truth for server-state retention / model-binding.
+     *  createLLM supplies `engine.catalog`. An empty catalog still yields correct
+     *  provider-level defaults, so this is optional. */
+    catalog?: ModelCatalog;
+}

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

@@ -0,0 +1,28 @@
+/** LLMClient internals — request normalization, system extraction, context
+ *  building, provider/adapter resolution, and structured-output parsing.
+ *  Split out of client.ts to keep the class file focused on the public surface. */
+import type { RequestContext } from '../types/request-context';
+import type { LLMClient } from './client';
+import type { LLMClientConfig } from './client-config';
+import type { ContentPart, Message } from './types/messages';
+import type { ExecuteOptions } from './types/options';
+import type { ApiType, ProviderAdapter, ProviderName } from './types/provider';
+export declare const PRIORITY_INTERACTIVE = 1;
+export declare const PRIORITY_BACKGROUND = 2;
+export declare function normalizeInput(input: string | ContentPart[] | Message[]): Message[];
+/** Lift any role:'system' messages out of the input array.
+ *  Anthropic and some other providers expect `system` as a top-level
+ *  parameter, not as a message role. By extracting here in the client we
+ *  give callers a single, provider-neutral way to set per-call system text:
+ *  either pass `options.system`, or include role:'system' messages in the
+ *  input (they get concatenated). Adapters never see role:'system'. */
+export declare function extractSystem(messages: Message[]): {
+    system?: string;
+    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;
+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

@@ -0,0 +1,68 @@
+/** LLMClient — Layer 2.
+ *
+ *  Format adapter only. Does NOT own a queue, retry policy, or cache.
+ *  Receives `fetch` (and optionally `fetchStream`) as injected functions.
+ *  The semantic layer is fixed at construction:
+ *    - `provider` + `model` + `apiKey` + `system` are immutable per instance.
+ *
+ *  Public methods:
+ *    - `complete(input, options?)`  → CompletionResponse
+ *    - `stream(input, options?)`    → AsyncIterable<StreamEvent>
+ *    - `destroy()`                   → emit lifecycle hook
+ *
+ *  Input shapes (`string | ContentPart[] | Message[]`):
+ *    - `string`         → wrap as `[{role:'user', content: string}]`
+ *    - `ContentPart[]`  → wrap as `[{role:'user', content: parts}]`
+ *    - `Message[]`      → use as the full messages array (REPLACE)
+ *
+ *  Hooks emitted: onClientCreate (in ctor), onMessageResolve, onBeforeSubmit,
+ *  onCompletion, onClientDestroy. */
+import type { HookBus } from '../bus/hook-bus';
+import type { ContentPart, Message } from './types/messages';
+import type { ExecuteOptions } from './types/options';
+import type { ApiType, ProviderName } from './types/provider';
+import type { CompletionResponse } from './types/response';
+import type { StreamEvent } from './types/stream';
+import type { LLMClientConfig } from './client-config';
+export declare class LLMClient {
+    readonly id: string;
+    /** Trace session id (from the engine, or self-minted for a standalone client). */
+    readonly sessionId: string;
+    readonly provider: ProviderName;
+    readonly model: string;
+    readonly system: string | undefined;
+    readonly hooks: HookBus;
+    readonly api: ApiType;
+    readonly mode: 'foreground' | 'background';
+    readonly batchable: boolean;
+    private readonly adapter;
+    private readonly fetchFn;
+    private readonly fetchStreamFn;
+    private readonly priority;
+    private readonly queueName;
+    private readonly configName;
+    private readonly cacheName;
+    private readonly cacheKeyFn?;
+    private readonly catalog;
+    constructor(config: LLMClientConfig);
+    destroy(): void;
+    /** Build an assistant history message from a response, stamped with provenance
+     *  (id, createdAt, origin). On a stateful API (responses / interactions) the
+     *  origin carries the server-state id so a later turn can continue server-side
+     *  instead of resending the transcript. Push the result into your messages
+     *  array between turns:
+     *
+     *    const r1 = await llm.complete(messages);
+     *    messages.push(llm.assistantMessage(r1));
+     *    messages.push({ role: 'user', content: 'follow-up' });
+     *    const r2 = await llm.complete(messages); // sends id + only the new turn
+     */
+    assistantMessage(response: CompletionResponse): Message;
+    /** Submit a request. Returns the parsed CompletionResponse. */
+    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
+     *  to T. Throws if the parse fails — callers should catch + retry. */
+    structuredComplete<T = unknown>(input: string | ContentPart[] | Message[], schema: Record<string, unknown>, options?: ExecuteOptions): Promise<T>;
+    stream(input: string | ContentPart[] | Message[], options?: ExecuteOptions): AsyncIterable<StreamEvent>;
+}

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

@@ -0,0 +1,5 @@
+/** Shared constants used across provider adapters. */
+/** PCM16 mono audio sample rate emitted by Gemini Live and OpenAI Realtime. */
+export declare const AUDIO_PCM16_SAMPLE_RATE_HZ = 24000;
+/** Default max_tokens / max_completion_tokens when the caller omits the field. */
+export declare const DEFAULT_MAX_TOKENS = 4096;

package/dist/llm/providers/_shared/response-utils.d.ts

@@ -0,0 +1,8 @@
+/** Shared response helpers used across provider adapters. */
+import type { FinishReason } from '../../types/response';
+/**
+ * Table-driven finish-reason mapper.
+ * Returns 'tool_use' when tool calls are present; otherwise looks up the
+ * provider's raw reason in reasonMap, falling back to 'stop'.
+ */
+export declare function extractFinishReason(hasToolCalls: boolean, providerReason: string | undefined, reasonMap: Record<string, FinishReason>): FinishReason;

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

@@ -0,0 +1,19 @@
+/** 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 { BatchProviderAdapter, BatchRequest, BatchResult, BatchStatus } from '../../../plugins/batch/types';
+export interface AnthropicBatchAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class AnthropicBatchAdapter implements BatchProviderAdapter {
+    readonly name = "anthropic";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: AnthropicBatchAdapterConfig);
+    private authHeaders;
+    submit(requests: BatchRequest[], fetch: EngineFetch): Promise<string>;
+    getStatus(batchId: string, fetch: EngineFetch): Promise<BatchStatus>;
+    getResults(batchId: string, fetch: EngineFetch): Promise<BatchResult[]>;
+    cancel(batchId: string, fetch: EngineFetch): Promise<void>;
+}

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

@@ -0,0 +1,13 @@
+/** Anthropic provider constants. */
+/** 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;

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

@@ -0,0 +1,23 @@
+/** Anthropic file adapter — POST /v1/files (beta).
+ *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
+import type { EngineFetch } from '../../../network/types';
+import type { FileAttachment } from '../../../plugins/files/attachment';
+import type { FileProviderAdapter, FileUploadResult, RemoteFileInfo } from '../../../plugins/files/provider-adapter';
+export interface AnthropicFileAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class AnthropicFileAdapter implements FileProviderAdapter {
+    readonly name = "anthropic";
+    readonly expiresAfter: null;
+    readonly maxFileSize = 500000000;
+    readonly supportedTypes: string[];
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: AnthropicFileAdapterConfig);
+    private authHeaders;
+    upload(file: FileAttachment, fetch: EngineFetch): Promise<FileUploadResult>;
+    delete(remoteId: string, fetch: EngineFetch): Promise<void>;
+    getInfo(remoteId: string, fetch: EngineFetch): Promise<RemoteFileInfo | null>;
+    list(fetch: EngineFetch): Promise<RemoteFileInfo[]>;
+}

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

@@ -0,0 +1,30 @@
+/** Anthropic provider adapter (Messages API).
+ *
+ *  Ported from llm-sdk verbatim. Only change: takes NormalizedRequest instead
+ *  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 { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { type CompletionResponse } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
+export interface AnthropicAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class AnthropicAdapter implements ProviderAdapter {
+    readonly name: "anthropic";
+    protected readonly apiKey: string;
+    protected readonly _baseURL?: string;
+    constructor(config: AnthropicAdapterConfig);
+    authHeaders(): Record<string, string>;
+    baseURL(): string;
+    completionPath(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
+    private buildMessage;
+    private buildContentPart;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    private parseUsage;
+}

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

@@ -0,0 +1,20 @@
+/** Google batch adapter — inline batchGenerateContent.
+ *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
+import type { EngineFetch } from '../../../network/types';
+import type { BatchProviderAdapter, BatchRequest, BatchResult, BatchStatus } from '../../../plugins/batch/types';
+export interface GoogleBatchAdapterConfig {
+    apiKey: string;
+    model?: string;
+    baseURL?: string;
+}
+export declare class GoogleBatchAdapter implements BatchProviderAdapter {
+    readonly name = "google";
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseURL;
+    constructor(config: GoogleBatchAdapterConfig);
+    submit(requests: BatchRequest[], fetch: EngineFetch): Promise<string>;
+    getStatus(batchId: string, fetch: EngineFetch): Promise<BatchStatus>;
+    getResults(batchId: string, fetch: EngineFetch): Promise<BatchResult[]>;
+    cancel(batchId: string, fetch: EngineFetch): Promise<void>;
+}

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

@@ -0,0 +1,6 @@
+/** Google provider constants. */
+/**
+ * Map from unified thinking effort levels to Gemini thinkingLevel enum strings.
+ * Used in both generate.ts and interactions.ts.
+ */
+export declare const GOOGLE_THINKING_LEVELS: Record<string, string>;

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

@@ -0,0 +1,15 @@
+/** 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 { EmbedRequest, EmbedResult, EmbeddingProviderAdapter } from '../../../plugins/embeddings/types';
+export interface GoogleEmbeddingAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class GoogleEmbeddingAdapter implements EmbeddingProviderAdapter {
+    readonly name = "google";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: GoogleEmbeddingAdapterConfig);
+    embed(req: EmbedRequest, fetch: EngineFetch): Promise<EmbedResult>;
+}

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

@@ -0,0 +1,22 @@
+/** 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 { FileAttachment } from '../../../plugins/files/attachment';
+import type { FileProviderAdapter, FileUploadResult, RemoteFileInfo } from '../../../plugins/files/provider-adapter';
+export interface GoogleFileAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class GoogleFileAdapter implements FileProviderAdapter {
+    readonly name = "google";
+    readonly expiresAfter: number;
+    readonly maxFileSize = 2000000000;
+    readonly supportedTypes: null;
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: GoogleFileAdapterConfig);
+    upload(file: FileAttachment, fetch: EngineFetch): Promise<FileUploadResult>;
+    delete(remoteId: string, fetch: EngineFetch): Promise<void>;
+    getInfo(remoteId: string, fetch: EngineFetch): Promise<RemoteFileInfo | null>;
+    list(fetch: EngineFetch): Promise<RemoteFileInfo[]>;
+}

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

@@ -0,0 +1,27 @@
+/** Google Gemini provider adapter (generateContent API). */
+import type { SSEEvent } from '../../../network/types';
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { type CompletionResponse } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
+export interface GoogleAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class GoogleAdapter implements ProviderAdapter {
+    readonly name: "google";
+    private readonly apiKey;
+    private readonly _baseURL?;
+    constructor(config: GoogleAdapterConfig);
+    authHeaders(): Record<string, string>;
+    baseURL(): string;
+    completionPath(): string;
+    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;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    private parseUsage;
+}

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

@@ -0,0 +1,30 @@
+/** Google Interactions API adapter.
+ *  Endpoint: POST /v1beta/interactions
+ *  Modern API: input, system_instruction, outputs (plural), function_result,
+ *  previous_interaction_id for stateful, 72h retention. */
+import type { SSEEvent } from '../../../network/types';
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { type CompletionResponse } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
+export interface GoogleInteractionsAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class GoogleInteractionsAdapter implements ProviderAdapter {
+    readonly name: "google";
+    private readonly apiKey;
+    private readonly _baseURL?;
+    constructor(config: GoogleInteractionsAdapterConfig);
+    authHeaders(): Record<string, string>;
+    baseURL(): string;
+    completionPath(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    private buildInputItems;
+    /** Track tool call IDs → names for function_result */
+    private toolCallNames;
+    enableStreaming(providerReq: ProviderHttpRequest): void;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    private parseUsage;
+}

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

@@ -0,0 +1,27 @@
+/** 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 { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult, VideoGenRequest, VideoStatus } from '../../../plugins/media/types';
+export interface GoogleMediaAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class GoogleMediaAdapter implements MediaProviderAdapter {
+    readonly name = "google";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: GoogleMediaAdapterConfig);
+    capabilities(): MediaCapabilities;
+    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;
+    submitVideo(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
+    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/google/realtime.d.ts

@@ -0,0 +1,27 @@
+/** Google Gemini Live adapter (Bidi over WebSocket).
+ *
+ *  Wire protocol (extracted from `@google/genai` live.ts):
+ *    - URL: wss://generativelanguage.googleapis.com/ws/
+ *           google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=<key>
+ *    - On open: send { setup: { model: 'models/<model>', generationConfig:
+ *      { responseModalities } , systemInstruction? } }. Server replies
+ *      { setupComplete: {} } → only then is the session ready for content.
+ *    - Send a turn: { clientContent: { turns: [{role:'user',parts:[{text}]}],
+ *      turnComplete } }.
+ *    - Server: { serverContent: { modelTurn: { parts: [{text}|{inlineData:
+ *      {mimeType,data(base64)}}] }, turnComplete? } }.
+ *
+ *  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';
+export interface GoogleRealtimeAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class GoogleRealtimeAdapter implements RealtimeProviderAdapter {
+    private readonly apiKey;
+    private readonly base;
+    constructor(config: GoogleRealtimeAdapterConfig);
+    connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
+}

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

@@ -0,0 +1,19 @@
+/** 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 { BatchProviderAdapter, BatchRequest, BatchResult, BatchStatus } from '../../../plugins/batch/types';
+export interface OpenAIBatchAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIBatchAdapter implements BatchProviderAdapter {
+    readonly name = "openai";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAIBatchAdapterConfig);
+    private bearer;
+    submit(requests: BatchRequest[], fetch: EngineFetch): Promise<string>;
+    getStatus(batchId: string, fetch: EngineFetch): Promise<BatchStatus>;
+    getResults(batchId: string, fetch: EngineFetch): Promise<BatchResult[]>;
+    cancel(batchId: string, fetch: EngineFetch): Promise<void>;
+}

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

@@ -0,0 +1,25 @@
+/** OpenAI provider adapter (Chat Completions API). */
+import type { SSEEvent } from '../../../network/types';
+import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { type CompletionResponse } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
+export interface OpenAIAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIAdapter implements ProviderAdapter {
+    readonly name: ProviderAdapter['name'];
+    protected readonly apiKey: string;
+    protected readonly _baseURL?: string;
+    constructor(config: OpenAIAdapterConfig);
+    authHeaders(): Record<string, string>;
+    baseURL(): string;
+    completionPath(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    private buildMessage;
+    enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    private parseUsage;
+}

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

@@ -0,0 +1,16 @@
+/** OpenAI embeddings adapter — POST /v1/embeddings. Also the base for the
+ *  OpenAI-compatible OpenRouter adapter. */
+import type { EngineFetch } from '../../../network/types';
+import type { EmbedRequest, EmbedResult, EmbeddingProviderAdapter } from '../../../plugins/embeddings/types';
+export interface OpenAIEmbeddingAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIEmbeddingAdapter implements EmbeddingProviderAdapter {
+    readonly name: string;
+    protected readonly apiKey: string;
+    protected readonly _baseURL: string;
+    constructor(config: OpenAIEmbeddingAdapterConfig);
+    protected embeddingsPath(): string;
+    embed(req: EmbedRequest, fetch: EngineFetch): Promise<EmbedResult>;
+}

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

@@ -0,0 +1,23 @@
+/** OpenAI file adapter — POST /v1/files.
+ *  All HTTP flows through the injected EngineFetch (NetworkEngine queue). */
+import type { EngineFetch } from '../../../network/types';
+import type { FileAttachment } from '../../../plugins/files/attachment';
+import type { FileProviderAdapter, FileUploadResult, RemoteFileInfo } from '../../../plugins/files/provider-adapter';
+export interface OpenAIFileAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIFileAdapter implements FileProviderAdapter {
+    readonly name = "openai";
+    readonly expiresAfter: null;
+    readonly maxFileSize = 50000000;
+    readonly supportedTypes: null;
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAIFileAdapterConfig);
+    private bearer;
+    upload(file: FileAttachment, fetch: EngineFetch): Promise<FileUploadResult>;
+    delete(remoteId: string, fetch: EngineFetch): Promise<void>;
+    getInfo(remoteId: string, fetch: EngineFetch): Promise<RemoteFileInfo | null>;
+    list(fetch: EngineFetch): Promise<RemoteFileInfo[]>;
+}

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

@@ -0,0 +1,28 @@
+/** 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 { AudioGenRequest, ImageEditRequest, ImageGenRequest, MediaCapabilities, MediaProviderAdapter, RawMediaResult, VideoGenRequest, VideoStatus } from '../../../plugins/media/types';
+export interface OpenAIMediaAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIMediaAdapter implements MediaProviderAdapter {
+    readonly name = "openai";
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAIMediaAdapterConfig);
+    capabilities(): MediaCapabilities;
+    private authHeaders;
+    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). */
+    private parseImages;
+    /** Image-to-image edit via `/v1/images/edits` (JSON, base64 data-URL or
+     *  file_id references). */
+    editImage(req: ImageEditRequest, fetch: EngineFetch): Promise<RawMediaResult[]>;
+    generateAudio(req: AudioGenRequest, fetch: EngineFetch): Promise<RawMediaResult>;
+    submitVideo(req: VideoGenRequest, fetch: EngineFetch): Promise<string>;
+    getVideoStatus(videoId: string, fetch: EngineFetch): Promise<VideoStatus>;
+    downloadVideo(videoId: string, fetch: EngineFetch): Promise<RawMediaResult>;
+}

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

@@ -0,0 +1,19 @@
+/** OpenAI moderations adapter -- POST /v1/moderations.
+ *  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 { ModerationContentPart, ModerationResult } from '../../../helpers/moderate-types';
+export interface OpenAIModerationAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare const OPENAI_MODERATION_BASE_URL = "https://api.openai.com";
+export declare const OPENAI_MODERATION_PATH = "/v1/moderations";
+export declare const OPENAI_MODERATION_DEFAULT_MODEL = "omni-moderation-latest";
+export declare class OpenAIModerationAdapter {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAIModerationAdapterConfig);
+    moderate(input: string | string[] | ModerationContentPart | ModerationContentPart[], model: string, fetch: EngineFetch): Promise<ModerationResult[]>;
+}

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

@@ -0,0 +1,24 @@
+/** OpenAI realtime adapter (GA `wss://api.openai.com/v1/realtime`).
+ *
+ *  Wire protocol (extracted from the official `openai/realtime/websocket`):
+ *    - Auth via WS subprotocols: ['realtime', 'openai-insecure-api-key.<key>'].
+ *    - On open: session.update { session: { type:'realtime', output_modalities } }.
+ *    - Send a turn: conversation.item.create (input_text / input_audio) then
+ *      response.create.
+ *    - Server events keyed by `.type`:
+ *        response.output_text.delta   → { text, delta }
+ *        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';
+export interface OpenAIRealtimeAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIRealtimeAdapter implements RealtimeProviderAdapter {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAIRealtimeAdapterConfig);
+    connect(config: RealtimeSessionConfig, connect: EngineConnect): RealtimeSession;
+}

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

@@ -0,0 +1,29 @@
+/** OpenAI Responses API adapter.
+ *  Endpoint: POST /v1/responses
+ *  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 { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
+import type { NormalizedRequest } from '../../types/request';
+import { type CompletionResponse, type Usage } from '../../types/response';
+import type { StreamEvent } from '../../types/stream';
+export interface OpenAIResponsesAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare class OpenAIResponsesAdapter implements ProviderAdapter {
+    readonly name: ProviderAdapter['name'];
+    protected readonly apiKey: string;
+    protected readonly _baseURL?: string;
+    constructor(config: OpenAIResponsesAdapterConfig);
+    authHeaders(): Record<string, string>;
+    baseURL(): string;
+    completionPath(): string;
+    buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** Convert a universal Message to Responses API input items */
+    private buildInputItems;
+    enableStreaming(providerReq: ProviderHttpRequest): void;
+    parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
+    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    protected parseUsage(u: Record<string, unknown> | undefined): Usage;
+}