@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/providers/openai-compat/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Wire types for the internal OpenAI-compatible Chat Completions client.
+ *
+ * These model only the fields NodeTool reads or writes — not the full OpenAI
+ * schema. Gateways diverge from OpenAI in the long tail, so every response
+ * field is optional and unknown extra request params ride the index signature.
+ */
+/** Request body for `POST /chat/completions`. */
+export interface ChatCompletionsRequest {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    stream?: boolean;
+    /** Extra params (temperature, tools, stream_options, …) pass through as-is. */
+    [param: string]: unknown;
+}
+export interface ChatCompletionUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+}
+export interface ChatCompletionToolCallFunction {
+    name?: string | null;
+    arguments?: string | null;
+}
+export interface ChatCompletionMessageToolCall {
+    id?: string | null;
+    type?: string;
+    function?: ChatCompletionToolCallFunction;
+}
+export interface ChatCompletionAssistantMessage {
+    role?: string;
+    content?: string | null;
+    tool_calls?: ChatCompletionMessageToolCall[] | null;
+}
+export interface ChatCompletionChoice {
+    index?: number;
+    message?: ChatCompletionAssistantMessage;
+    finish_reason?: string | null;
+}
+/** Non-streaming response from `POST /chat/completions`. */
+export interface ChatCompletionResponse {
+    id?: string;
+    model?: string;
+    choices?: ChatCompletionChoice[];
+    usage?: ChatCompletionUsage | null;
+}
+export interface ChatCompletionChunkDeltaToolCall {
+    index?: number;
+    id?: string | null;
+    function?: ChatCompletionToolCallFunction;
+}
+export interface ChatCompletionChunkDelta {
+    content?: string | null;
+    tool_calls?: ChatCompletionChunkDeltaToolCall[] | null;
+    /** Audio-output models (`modalities: ["text","audio"]`) stream base64 here. */
+    audio?: {
+        data?: string;
+    };
+}
+export interface ChatCompletionChunkChoice {
+    index?: number;
+    delta?: ChatCompletionChunkDelta;
+    finish_reason?: string | null;
+}
+/** One SSE chunk of a streaming chat completion. */
+export interface ChatCompletionChunk {
+    id?: string;
+    model?: string;
+    choices?: ChatCompletionChunkChoice[];
+    usage?: ChatCompletionUsage | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/openai-compat/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-compat/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,8BAA8B,CAAC;CAC3C;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,6BAA6B,EAAE,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,8BAA8B,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACjC,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,gCAAgC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,CAAC,EAAE,8BAA8B,CAAC;CAC3C;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,gCAAgC,EAAE,GAAG,IAAI,CAAC;IACvD,+EAA+E;IAC/E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACtC,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACpC"}

package/dist/providers/openai-compat/types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types for the internal OpenAI-compatible Chat Completions client.
+ *
+ * These model only the fields NodeTool reads or writes — not the full OpenAI
+ * schema. Gateways diverge from OpenAI in the long tail, so every response
+ * field is optional and unknown extra request params ride the index signature.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/providers/openai-compat/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/providers/openai-compat/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/providers/openai-compat-provider.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Base class for providers that speak the OpenAI Chat Completions dialect
+ * against a non-OpenAI endpoint (Groq, Cerebras, xAI, Mistral, DeepSeek, …).
+ *
+ * Chat — the only surface these providers ever used the `openai` npm package
+ * for — runs on the internal {@link OpenAICompatClient} over `fetch`. The SDK
+ * client inherited from {@link OpenAIProvider} remains as a lazily-created
+ * fallback for the OpenAI-compatible media/embedding endpoints some gateways
+ * also expose (Together ASR, OpenRouter images, Mistral embeddings); it is
+ * never constructed on the chat path.
+ */
+import OpenAI from "openai";
+import { OpenAIProvider } from "./openai-provider.js";
+import { OpenAICompatClient, type ChatCompletionsRequest } from "./openai-compat/index.js";
+import type { LanguageModel, Message, ProviderId, ProviderStreamItem } from "./types.js";
+import type { BaseProvider } from "./base-provider.js";
+interface OpenAICompatConfig {
+    /** Provider id reported by this instance (e.g. `"groq"`). */
+    providerId: ProviderId;
+    apiKey: string;
+    /** Chat endpoint root, e.g. `https://api.groq.com/openai/v1`. */
+    baseURL: string;
+    /** Extra headers on every chat request (gateway attribution etc.). */
+    defaultHeaders?: Record<string, string>;
+}
+export interface OpenAICompatProviderOptions {
+    /** SDK client used only by inherited non-chat surfaces (images, ASR, …). */
+    client?: OpenAI;
+    clientFactory?: (apiKey: string) => OpenAI;
+    fetchFn?: typeof fetch;
+    /** Internal chat client override (tests). */
+    compatClient?: OpenAICompatClient;
+}
+/** One row of a `GET /models` listing: an id plus whatever else the vendor sent. */
+export type CompatModelRow = Record<string, unknown> & {
+    id: string;
+};
+export declare class OpenAICompatProvider extends OpenAIProvider {
+    private _compatClient;
+    private readonly _compatConfig;
+    private readonly _compatFetch;
+    constructor(config: OpenAICompatConfig, options?: OpenAICompatProviderOptions);
+    /** The injected (or global) `fetch`, for surfaces this class does not cover. */
+    protected get compatFetch(): typeof fetch;
+    /** Chat endpoint root this instance was configured with. */
+    protected get compatBaseURL(): string;
+    /**
+     * Decode an OpenAI-shaped `GET /models` listing into language models tagged
+     * with this provider's id.
+     *
+     * A failed request answers `[]` rather than throwing: model discovery runs
+     * on every picker open, across every configured provider, and one bad key
+     * must not break the others. The status is logged so a user staring at an
+     * empty list can find the 401 in the log.
+     */
+    protected listCompatModels(url?: string, init?: {
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<LanguageModel[]>;
+    /**
+     * The raw rows of an OpenAI-shaped `GET /models` listing, keeping every
+     * field the endpoint sent so callers can read vendor metadata (a `type`,
+     * output modalities) beyond the id. Rows without a string id are dropped;
+     * a failed request answers `[]` for the reason given on
+     * {@link listCompatModels}.
+     */
+    protected fetchCompatModelRows(url?: string, init?: {
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<CompatModelRow[]>;
+    protected getCompatClient(): OpenAICompatClient;
+    /** Shared request assembly for both streaming and non-streaming chat. */
+    private buildChatRequest;
+    /**
+     * Last edit of the assembled request before dispatch. Subclasses override
+     * this when their endpoint deviates from OpenAI's dialect — e.g. a provider
+     * that only accepts `max_tokens` instead of `max_completion_tokens`.
+     */
+    protected transformChatRequest(request: ChatCompletionsRequest): ChatCompletionsRequest;
+    /**
+     * Provider-specific classification for an OpenAI-compatible failure. The
+     * request is the final converted wire payload, so subclasses can diagnose
+     * vendor limits without rebuilding or logging caller messages.
+     */
+    protected handleCompatError(error: unknown, _request: ChatCompletionsRequest): unknown;
+    generateMessages(args: Parameters<BaseProvider["generateMessages"]>[0]): AsyncGenerator<ProviderStreamItem>;
+    generateMessage(args: Parameters<BaseProvider["generateMessage"]>[0]): Promise<Message>;
+}
+export {};
+//# sourceMappingURL=openai-compat-provider.d.ts.map

package/dist/providers/openai-compat-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-compat-provider.d.ts","sourceRoot":"","sources":["../../src/providers/openai-compat-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAO5B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAElB,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,aAAa,EACb,OAAO,EACP,UAAU,EACV,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,UAAU,kBAAkB;IAC1B,6DAA6D;IAC7D,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAQtE,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C,YACE,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,2BAAgC,EAyB1C;IAED,gFAAgF;IAChF,SAAS,KAAK,WAAW,IAAI,OAAO,KAAK,CAExC;IAED,4DAA4D;IAC5D,SAAS,KAAK,aAAa,IAAI,MAAM,CAEpC;IAED;;;;;;;;OAQG;IACH,UAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAA+C,EACpD,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACpE,OAAO,CAAC,aAAa,EAAE,CAAC,CAO1B;IAED;;;;;;OAMG;IACH,UAAgB,oBAAoB,CAClC,GAAG,GAAE,MAA+C,EACpD,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACpE,OAAO,CAAC,cAAc,EAAE,CAAC,CA8B3B;IAED,SAAS,CAAC,eAAe,IAAI,kBAAkB,CAU9C;IAED,yEAAyE;YAC3D,gBAAgB;IA+D9B;;;;OAIG;IACH,SAAS,CAAC,oBAAoB,CAC5B,OAAO,EAAE,sBAAsB,GAC9B,sBAAsB,CAExB;IAED;;;;OAIG;IACH,SAAS,CAAC,iBAAiB,CACzB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAET;IAEe,gBAAgB,CAC9B,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,GACpD,cAAc,CAAC,kBAAkB,CAAC,CA0FpC;IAEc,eAAe,CAC5B,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,OAAO,CAAC,OAAO,CAAC,CAuClB;CACF"}

package/dist/providers/openai-compat-provider.js

@@ -0,0 +1,282 @@
+/**
+ * Base class for providers that speak the OpenAI Chat Completions dialect
+ * against a non-OpenAI endpoint (Groq, Cerebras, xAI, Mistral, DeepSeek, …).
+ *
+ * Chat — the only surface these providers ever used the `openai` npm package
+ * for — runs on the internal {@link OpenAICompatClient} over `fetch`. The SDK
+ * client inherited from {@link OpenAIProvider} remains as a lazily-created
+ * fallback for the OpenAI-compatible media/embedding endpoints some gateways
+ * also expose (Together ASR, OpenRouter images, Mistral embeddings); it is
+ * never constructed on the chat path.
+ */
+import OpenAI from "openai";
+import { isNonEmptyString, isRecord } from "@nodetool-ai/protocol";
+import { createLogger } from "@nodetool-ai/config";
+import { OpenAIProvider } from "./openai-provider.js";
+import { OpenAICompatClient, decodeChatCompletion } from "./openai-compat/index.js";
+const log = createLogger("nodetool.runtime.providers.openai-compat");
+export class OpenAICompatProvider extends OpenAIProvider {
+    _compatClient;
+    _compatConfig;
+    _compatFetch;
+    constructor(config, options = {}) {
+        super({ OPENAI_API_KEY: config.apiKey }, {
+            providerId: config.providerId,
+            client: options.client,
+            clientFactory: options.clientFactory ??
+                ((key) => {
+                    const clientOptions = {
+                        apiKey: key,
+                        baseURL: config.baseURL
+                    };
+                    if (config.defaultHeaders) {
+                        clientOptions.defaultHeaders = config.defaultHeaders;
+                    }
+                    return new OpenAI(clientOptions);
+                }),
+            fetchFn: options.fetchFn
+        });
+        this._compatConfig = config;
+        this._compatClient = options.compatClient ?? null;
+        this._compatFetch = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+    }
+    /** The injected (or global) `fetch`, for surfaces this class does not cover. */
+    get compatFetch() {
+        return this._compatFetch;
+    }
+    /** Chat endpoint root this instance was configured with. */
+    get compatBaseURL() {
+        return this._compatConfig.baseURL;
+    }
+    /**
+     * Decode an OpenAI-shaped `GET /models` listing into language models tagged
+     * with this provider's id.
+     *
+     * A failed request answers `[]` rather than throwing: model discovery runs
+     * on every picker open, across every configured provider, and one bad key
+     * must not break the others. The status is logged so a user staring at an
+     * empty list can find the 401 in the log.
+     */
+    async listCompatModels(url = `${this._compatConfig.baseURL}/models`, init = {}) {
+        const rows = await this.fetchCompatModelRows(url, init);
+        return rows.map((row) => ({
+            id: row.id,
+            name: isNonEmptyString(row.name) ? row.name : row.id,
+            provider: this.provider
+        }));
+    }
+    /**
+     * The raw rows of an OpenAI-shaped `GET /models` listing, keeping every
+     * field the endpoint sent so callers can read vendor metadata (a `type`,
+     * output modalities) beyond the id. Rows without a string id are dropped;
+     * a failed request answers `[]` for the reason given on
+     * {@link listCompatModels}.
+     */
+    async fetchCompatModelRows(url = `${this._compatConfig.baseURL}/models`, init = {}) {
+        const request = {
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                // Same precedence as OpenAICompatClient: a configured header (gateway
+                // attribution, a non-Bearer auth scheme) wins over the default.
+                ...this._compatConfig.defaultHeaders,
+                ...init.headers
+            }
+        };
+        if (init.signal) {
+            request.signal = init.signal;
+        }
+        const response = await this._compatFetch(url, request);
+        if (!response.ok) {
+            log.warn("Model listing failed", {
+                provider: this.provider,
+                url,
+                status: response.status
+            });
+            return [];
+        }
+        const payload = await response.json();
+        const rows = isRecord(payload) ? payload.data : undefined;
+        // Stryker disable next-line ArrayDeclaration: the fallback is filtered downstream (rows need a string id), so [] vs any array is observably identical.
+        return (Array.isArray(rows) ? rows : [])
+            .filter(isRecord)
+            .filter((row) => isNonEmptyString(row.id));
+    }
+    getCompatClient() {
+        if (!this._compatClient) {
+            this._compatClient = new OpenAICompatClient({
+                baseURL: this._compatConfig.baseURL,
+                apiKey: this._compatConfig.apiKey,
+                defaultHeaders: this._compatConfig.defaultHeaders,
+                fetchFn: this._compatFetch
+            });
+        }
+        return this._compatClient;
+    }
+    /** Shared request assembly for both streaming and non-streaming chat. */
+    async buildChatRequest(args, stream) {
+        const { model, tools = [], toolChoice, maxTokens = 16384, temperature, topP, presencePenalty, frequencyPenalty, audio } = args;
+        const messages = this.convertSystemToUserForOModels(args.messages, model);
+        const openaiMessages = await Promise.all(messages.map((m) => this.convertMessage(m)));
+        const request = {
+            model,
+            messages: openaiMessages,
+            max_completion_tokens: maxTokens,
+            stream
+        };
+        if (stream)
+            request.stream_options = { include_usage: true };
+        if (temperature != null)
+            request.temperature = temperature;
+        if (topP != null)
+            request.top_p = topP;
+        if (presencePenalty != null)
+            request.presence_penalty = presencePenalty;
+        if (frequencyPenalty != null)
+            request.frequency_penalty = frequencyPenalty;
+        if (audio) {
+            request.audio = audio;
+            request.modalities = ["text", "audio"];
+        }
+        if (tools.length > 0 && (await this.hasToolSupport(model))) {
+            request.tools = this.formatTools(tools);
+            if (toolChoice) {
+                request.tool_choice =
+                    toolChoice === "any"
+                        ? "required"
+                        : { type: "function", function: { name: toolChoice } };
+            }
+        }
+        return this.transformChatRequest(request);
+    }
+    /**
+     * Last edit of the assembled request before dispatch. Subclasses override
+     * this when their endpoint deviates from OpenAI's dialect — e.g. a provider
+     * that only accepts `max_tokens` instead of `max_completion_tokens`.
+     */
+    transformChatRequest(request) {
+        return request;
+    }
+    /**
+     * Provider-specific classification for an OpenAI-compatible failure. The
+     * request is the final converted wire payload, so subclasses can diagnose
+     * vendor limits without rebuilding or logging caller messages.
+     */
+    handleCompatError(error, _request) {
+        return error;
+    }
+    async *generateMessages(args) {
+        const { model } = args;
+        const request = await this.buildChatRequest(args, true);
+        log.debug("OpenAI-compatible chat request", {
+            provider: this.provider,
+            model
+        });
+        this.recordRequestPayload(request);
+        const deltaToolCalls = new Map();
+        try {
+            const stream = this.getCompatClient().chatCompletionsStream(request, {
+                signal: args.signal
+            });
+            for await (const chunk of stream) {
+                if (chunk.usage) {
+                    this.trackUsage(model, {
+                        inputTokens: chunk.usage.prompt_tokens ?? 0,
+                        outputTokens: chunk.usage.completion_tokens ?? 0,
+                        cachedTokens: chunk.usage.prompt_tokens_details?.cached_tokens ?? 0
+                    });
+                }
+                const choice = chunk.choices?.[0];
+                if (!choice)
+                    continue;
+                const delta = choice.delta;
+                if (delta?.audio?.data) {
+                    const audioChunk = {
+                        type: "chunk",
+                        content_type: "audio",
+                        content: String(delta.audio.data)
+                    };
+                    yield audioChunk;
+                }
+                if (Array.isArray(delta?.tool_calls)) {
+                    for (const tc of delta.tool_calls) {
+                        const index = Number(tc.index ?? 0);
+                        const current = deltaToolCalls.get(index) ?? {
+                            id: String(tc.id ?? ""),
+                            name: String(tc.function?.name ?? ""),
+                            arguments: ""
+                        };
+                        if (tc.id)
+                            current.id = String(tc.id);
+                        if (tc.function?.name)
+                            current.name = String(tc.function.name);
+                        if (tc.function?.arguments)
+                            current.arguments += String(tc.function.arguments);
+                        deltaToolCalls.set(index, current);
+                    }
+                }
+                if (delta?.content !== undefined || choice.finish_reason === "stop") {
+                    const item = {
+                        type: "chunk",
+                        content: String(delta?.content ?? ""),
+                        done: choice.finish_reason === "stop"
+                    };
+                    yield item;
+                }
+                if (choice.finish_reason && deltaToolCalls.size > 0) {
+                    for (const call of deltaToolCalls.values()) {
+                        const toolCall = this.buildToolCall(call.id, call.name, call.arguments);
+                        yield toolCall;
+                    }
+                    deltaToolCalls.clear();
+                }
+                // Always emit a terminal `done: true` chunk when the completion
+                // finishes, regardless of reason. "stop" already emits one above; for
+                // every other terminal reason (tool_calls, length, content_filter)
+                // emit one here so consumers get a consistent end-of-stream marker.
+                if (choice.finish_reason && choice.finish_reason !== "stop") {
+                    const doneChunk = { type: "chunk", content: "", done: true };
+                    yield doneChunk;
+                }
+            }
+        }
+        catch (error) {
+            throw this.handleCompatError(error, request);
+        }
+    }
+    async generateMessage(args) {
+        const { model } = args;
+        const request = await this.buildChatRequest(args, false);
+        log.debug("OpenAI-compatible chat request", {
+            provider: this.provider,
+            model
+        });
+        this.recordRequestPayload(request);
+        let completion;
+        try {
+            completion = await this.getCompatClient().chatCompletions(request, {
+                signal: args.signal
+            });
+        }
+        catch (error) {
+            throw this.handleCompatError(error, request);
+        }
+        let decoded;
+        try {
+            decoded = decodeChatCompletion(completion);
+        }
+        catch {
+            // The decoder rejects exactly the bodies this path cannot turn into a
+            // message; keep the wording callers already match on.
+            throw new Error(`${this.provider} returned no choices`);
+        }
+        if (decoded.usage)
+            this.trackUsage(model, decoded.usage);
+        const toolCalls = decoded.toolCalls?.map((tc) => this.buildToolCall(tc.id, tc.name, tc.arguments));
+        return {
+            role: "assistant",
+            content: decoded.content,
+            toolCalls
+        };
+    }
+}
+//# sourceMappingURL=openai-compat-provider.js.map

package/dist/providers/openai-compat-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-compat-provider.js","sourceRoot":"","sources":["../../src/providers/openai-compat-provider.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai-provider.d.ts

@@ -1,11 +1,32 @@
 import OpenAI from "openai";
 import { BaseProvider } from "./base-provider.js";
-import type { ASRModel, EmbeddingModel, EncodedAudioResult, ImageModel, ImageToImageParams, ImageToVideoParams, LanguageModel, Message, ProviderStreamItem, ProviderTool, StreamingAudioChunk, TextToImageParams, TextToVideoParams, TTSModel, VideoModel } from "./types.js";
+import type { RunBudget, TurnBudget } from "../turn-budget.js";
+import type { ASRModel, EmbeddingModel, EncodedAudioResult, ImageModel, ImageToImageParams, InpaintingParams, ImageToVideoParams, LanguageModel, Message, MessageContent, ProviderId, ProviderStreamItem, ProviderTool, StreamingAudioChunk, TextToImageParams, TextToVideoParams, ToolCall, TTSModel, VideoModel } from "./types.js";
 interface OpenAIProviderOptions {
     client?: OpenAI;
     clientFactory?: (apiKey: string) => OpenAI;
     fetchFn?: typeof fetch;
+    /**
+     * Provider id reported by this instance. Defaults to `"openai"`.
+     * OpenAI-compatible subclasses (gateways pointed at a different base URL)
+     * pass their own id so the readonly `provider` field is set via the base
+     * constructor rather than reassigned afterwards.
+     */
+    providerId?: ProviderId;
 }
+export declare const OPENAI_FALLBACK_MODELS: LanguageModel[];
+/**
+ * Decode a `GET /v1/models` body into the language models it announces.
+ *
+ * Split out of {@link OpenAIProvider.getAvailableLanguageModels} so the live
+ * contract probe and its raw-response fixtures parse a real production
+ * response the same way the provider does. Strict on the envelope: a body
+ * without a `data` array throws, and the caller decides what to fall back to.
+ */
+export declare function decodeOpenAIModelList(payload: unknown, options: {
+    provider: ProviderId;
+    onlyResponsesModels: boolean;
+}): LanguageModel[];
 export declare class OpenAIProvider extends BaseProvider {
     static requiredSecrets(): string[];
     readonly apiKey: string;
@@ -17,16 +38,45 @@ export declare class OpenAIProvider extends BaseProvider {
     }, options?: OpenAIProviderOptions);
     getContainerEnv(): Record<string, string>;
     getClient(): OpenAI;
+    /**
+     * True when this instance should serve `model` through the Responses API.
+     * Gated on the real `openai` provider so OpenAI-compatible subclasses (which
+     * pass their own provider id) stay on Chat Completions.
+     */
+    protected usesResponsesApi(model: string): boolean;
+    get supportsNativeWebSearch(): boolean;
+    get supportsNativeImageGeneration(): boolean;
     hasToolSupport(model: string): Promise<boolean>;
+    /**
+     * Whether this instance actually serves OpenAI's own model catalog.
+     *
+     * The media and embedding lists below are hardcoded OpenAI models tagged
+     * `provider: "openai"`. Subclasses inherit OpenAI's *chat dialect*, not its
+     * lineup — a Groq or vLLM instance offering `gpt-image-2` or `whisper-1` is
+     * always wrong, and picking one sends the request to a host that has no such
+     * endpoint. Subclasses that do serve media (Together, MiniMax, GMI, xAI, …)
+     * override these methods with their own catalog; everyone else correctly
+     * reports none.
+     */
+    protected servesOpenAICatalog(): boolean;
     getAvailableLanguageModels(): Promise<LanguageModel[]>;
     getAvailableTTSModels(): Promise<TTSModel[]>;
     getAvailableASRModels(): Promise<ASRModel[]>;
     getAvailableVideoModels(): Promise<VideoModel[]>;
     getAvailableImageModels(): Promise<ImageModel[]>;
     getAvailableEmbeddingModels(): Promise<EmbeddingModel[]>;
-    resolveImageSize(width?: number | null, height?: number | null): string | null;
-    static resolveVideoSize(aspectRatio?: string | null, resolution?: string | null): string | null;
+    /**
+     * gpt-image-2 accepts arbitrary sizes within limits: both edges a multiple of
+     * 16, long edge <= 3840, aspect ratio <= 3:1, and total area between 0.64MP
+     * and 8.3MP. Requested sizes rarely land on that grid (16:9 at 1K is
+     * 1820x1024), so snap to the nearest valid size preserving the aspect ratio
+     * rather than dropping `size` and letting the API default to a square.
+     */
+    static snapToGptImage2Size(width: number, height: number): string | null;
+    resolveImageSize(width?: number | null, height?: number | null, model?: string): string | null;
+    static resolveVideoSize(aspectRatio?: string | null, resolution?: string | null, model?: string): string | null;
     static secondsFromParams(params: {
+        durationSeconds?: number | null;
         numFrames?: number | null;
     }): number | null;
     static snapToValidVideoDimensions(width: number, height: number): string;
@@ -36,36 +86,46 @@ export declare class OpenAIProvider extends BaseProvider {
     private messageContentToOpenAIContentPart;
     convertMessage(message: Message): Promise<Record<string, unknown>>;
     formatTools(tools: ProviderTool[]): Array<Record<string, unknown>>;
-    private convertSystemToUserForOModels;
-    generateMessages(args: {
-        messages: Message[];
-        model: string;
-        tools?: ProviderTool[];
-        maxTokens?: number;
-        temperature?: number;
-        topP?: number;
-        presencePenalty?: number;
-        frequencyPenalty?: number;
-        audio?: Record<string, unknown>;
+    protected convertSystemToUserForOModels(messages: Message[], model: string): Message[];
+    generateMessages(args: Parameters<BaseProvider["generateMessages"]>[0]): AsyncGenerator<ProviderStreamItem>;
+    generateMessage(args: Parameters<BaseProvider["generateMessage"]>[0]): Promise<Message>;
+    /** Tool shapes for the Responses API: native web_search / image_generation. */
+    private formatResponsesTools;
+    private generateMessageResponses;
+    private generateMessagesResponses;
+    generateLoop(args: Parameters<BaseProvider["generateMessages"]>[0] & {
+        executeTool?: (toolCall: ToolCall) => Promise<string | MessageContent[]>;
+        maxIterations?: number;
+        sequentialTools?: boolean;
+        turnBudget?: TurnBudget | RunBudget;
+        resolveMedia?: (messages: Message[]) => Promise<Message[]>;
     }): AsyncGenerator<ProviderStreamItem>;
-    generateMessage(args: {
-        messages: Message[];
-        model: string;
-        tools?: ProviderTool[];
-        toolChoice?: string | "any";
-        maxTokens?: number;
-        temperature?: number;
-        topP?: number;
-        presencePenalty?: number;
-        frequencyPenalty?: number;
-    }): Promise<Message>;
+    private buildResponsesRequest;
+    private streamResponsesRequest;
+    private createResponsesTurnState;
+    private runResponsesLoop;
+    private collectResponsesTurn;
     textToImage(params: TextToImageParams): Promise<Uint8Array>;
-    imageToImage(image: Uint8Array, params: ImageToImageParams): Promise<Uint8Array>;
+    /**
+     * Convert a white-region mask (R=G=B=255, alpha = selection) into the mask
+     * OpenAI's edit endpoint expects, where fully transparent pixels mark the
+     * region to regenerate. Inverts the alpha channel and keeps RGBA shape.
+     */
+    private toOpenAiEditMask;
+    imageToImage(images: Uint8Array[], params: ImageToImageParams): Promise<Uint8Array>;
+    inpaint(images: Uint8Array[], params: InpaintingParams): Promise<Uint8Array>;
+    /**
+     * Shared OpenAI image-edit call for both image-to-image and inpaint. When
+     * `mask` is supplied the masked region is regenerated.
+     */
+    private runImageEdit;
     textToSpeech(args: {
         text: string;
         model: string;
         voice?: string;
         speed?: number;
+        language?: string;
+        instructions?: string;
         audioFormat?: string;
     }): AsyncGenerator<StreamingAudioChunk>;
     /**
@@ -80,6 +140,8 @@ export declare class OpenAIProvider extends BaseProvider {
         model: string;
         voice?: string;
         speed?: number;
+        language?: string;
+        instructions?: string;
         audioFormat?: string;
     }): Promise<EncodedAudioResult | null>;
     automaticSpeechRecognition(args: {
@@ -97,6 +159,7 @@ export declare class OpenAIProvider extends BaseProvider {
         model: string;
         dimensions?: number;
     }): Promise<number[][]>;
+    isContextExceededError(error: unknown): boolean;
     isContextLengthError(error: unknown): boolean;
 }
 export {};