@veryfront/ext-llm-openai 0.1.1186 → 0.1.1189

package/README.md

@@ -2,7 +2,7 @@
 
 > **Category:** LLM | **Contract:** `LLMProvider` | **Built-in**
 
-Provides OpenAI models for Veryfront agents and chat, enabling `openai/*` models for chat, embeddings, and the Responses API via the `LLMProviderRegistry`.
+Provides OpenAI models for Veryfront agents and chat, enabling `openai/*` models for chat, embeddings, the Responses API, and OpenAI-hosted web search via the `LLMProviderRegistry`.
 
 ## Registration
 
@@ -43,7 +43,8 @@ const result = await ai.embed("openai/text-embedding-3-small", {
 
 ### Responses API
 
-For models that support OpenAI's Responses API (structured output, native tools):
+For models that support OpenAI's Responses API (structured output, function
+tools, and supported hosted tools):
 
 ```ts
 const response = await ai.responses("openai/gpt-4.1", {
@@ -51,6 +52,52 @@ const response = await ai.responses("openai/gpt-4.1", {
 });
 ```
 
+### Hosted Web Search
+
+The agent-facing tool name is `web_search`. It resolves to the current
+`openai.web_search` provider tool and routes that request through the Responses
+API, including for models that otherwise use Chat Completions:
+
+```ts
+import { agent } from "veryfront/agent";
+
+export default agent({
+  model: "openai/gpt-4.1",
+  providerTools: ["web_search"],
+});
+```
+
+| Contract                    | Supported value                                                                                     |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| Agent tool name             | `web_search`                                                                                        |
+| Current provider id         | `openai.web_search`                                                                                 |
+| Low-level compatibility ids | `openai.web_search_2025_08_26`, `openai.web_search_preview`, `openai.web_search_preview_2025_03_11` |
+| Optional argument           | `searchContextSize`: `"low"` \| `"medium"` \| `"high"`                                              |
+| Per-request limit           | One OpenAI web-search provider tool                                                                 |
+
+Other OpenAI-hosted tool types are not normalized by this extension and fail
+before the provider request. OpenAI-compatible base URLs can use this path only
+when the endpoint implements OpenAI's Responses and hosted web-search
+contracts.
+
+Responses requests are stateless (`store: false`). The runtime retains the
+complete ordered response output in provider metadata and replays it on the
+next turn. Reasoning requests explicitly include encrypted reasoning content,
+and web-search requests include source URLs, so manual callers must preserve
+assistant-message provider metadata between turns. Raw replay is limited to
+4,096 output items and 8 MiB. Whenever canonical calls or results survive,
+their IDs, names, semantic values, multiplicity, and order must match the raw
+output before transport.
+
+Provider-executed Responses calls and results cannot be converted into Chat
+Completions history. Switching a conversation containing those parts to a
+Chat Completions-only route fails as a configuration error before transport;
+keep that conversation on a Responses-capable route or begin a new compacted
+history that no longer contains the provider-executed parts.
+
+See [Providers: Enable OpenAI-hosted web search](../../docs/guides/providers.md#enable-openai-hosted-web-search)
+for the agent setup.
+
 ## Supported Models
 
 Any model accessible through the OpenAI Chat Completions, Responses, or Embeddings API:

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,12 @@
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAeA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd;;;;WAIG;QACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;KAC5C;CACF;AAED,OAAO,EAAE,CAAC"}

package/esm/_dnt.polyfills.js

@@ -0,0 +1,15 @@
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}
+export {};

package/esm/index.d.ts

@@ -4,6 +4,7 @@
  *
  * @module extensions/ext-llm-openai
  */
+import "./_dnt.polyfills.js";
 import type { ExtensionFactory } from "veryfront/extensions";
 import { OpenAIProvider } from "./openai-provider.js";
 declare const extOpenAI: ExtensionFactory;

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,QAAA,MAAM,SAAS,EAAE,gBAqBhB,CAAC;AAEF,eAAe,SAAS,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,QAAA,MAAM,SAAS,EAAE,gBAyBhB,CAAC;AAEF,eAAe,SAAS,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/esm/index.js

@@ -4,11 +4,13 @@
  *
  * @module extensions/ext-llm-openai
  */
+import "./_dnt.polyfills.js";
 import { LLMProviderRegistryName } from "veryfront/extensions/llm";
 import { OpenAIProvider } from "./openai-provider.js";
 const extOpenAI = () => {
     const provider = new OpenAIProvider();
     let registry;
+    let registeredProvider = false;
     return {
         name: "ext-llm-openai",
         version: "0.1.0",
@@ -19,11 +21,15 @@ const extOpenAI = () => {
         capabilities: [],
         setup(ctx) {
             registry = ctx.require(LLMProviderRegistryName);
+            registeredProvider = !registry.has(provider.id);
             registry.register(provider);
+            ctx.provide("LLMProvider:openai", registry.get(provider.id) ?? provider);
             ctx.logger.debug("[ext-llm-openai] OpenAI provider registered");
         },
         teardown() {
-            registry?.unregister(provider.id);
+            if (registeredProvider)
+                registry?.unregister(provider.id);
+            registeredProvider = false;
             registry = undefined;
         },
     };

package/esm/openai-chat-request-builder.d.ts

@@ -1,48 +1,10 @@
-import type { OpenAICompatibleChatRequest, RuntimePromptMessage } from "veryfront/provider/shared";
-import { type OpenAIProviderReasoningOption } from "./openai-reasoning-models.js";
-export type RuntimeToolDefinition = {
-    type: "function";
-    name: string;
-    description?: string;
-    inputSchema: unknown;
-} | {
-    type: "provider";
-    name: string;
-    id: `${string}.${string}`;
-    args: Record<string, unknown>;
-};
-export type OpenAICompatibleLanguageOptions = {
-    prompt: RuntimePromptMessage[];
-    maxOutputTokens?: number;
-    temperature?: number;
-    topP?: number;
-    topK?: number;
-    stopSequences?: string[];
-    tools?: RuntimeToolDefinition[];
-    toolChoice?: unknown;
-    seed?: number;
-    presencePenalty?: number;
-    frequencyPenalty?: number;
-    headers?: HeadersInit;
-    providerOptions?: Record<string, unknown>;
-    includeRawChunks?: boolean;
-    abortSignal?: AbortSignal;
-    reasoning?: OpenAIProviderReasoningOption;
-    userId?: string;
+import type { ModelRuntimeCallOptions, ModelRuntimeToolDefinition, OpenAICompatibleChatRequest } from "veryfront/provider/shared";
+export interface OpenAICompatibleLanguageOptions extends ModelRuntimeCallOptions {
     serviceTier?: "auto" | "default" | "flex" | "scale";
     parallelToolCalls?: boolean;
-    responseFormat?: {
-        type: "text";
-    } | {
-        type: "json";
-    } | {
-        type: "json_schema";
-        name: string;
-        schema: unknown;
-        description?: string;
-        strict?: boolean;
-    };
-};
+}
+/** @deprecated Import `ModelRuntimeToolDefinition` from `veryfront/provider` instead. */
+export type RuntimeToolDefinition = ModelRuntimeToolDefinition;
 type WarningCollector = {
     push(warning: {
         type: "unsupported-setting" | "other";

package/esm/openai-chat-request-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-chat-request-builder.d.ts","sourceRoot":"","sources":["../src/openai-chat-request-builder.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACnG,OAAO,EACL,KAAK,6BAA6B,EAGnC,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,qBAAqB,GAC7B;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GACC;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,CAAC;AAEJ,MAAM,MAAM,+BAA+B,GAAG;IAC5C,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,6BAA6B,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EACX;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QACA,IAAI,EAAE,aAAa,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACL,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACtB,IAAI,CAAC,OAAO,EAAE;QACZ,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC;QACtC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI,CAAC;IACT,KAAK,IAAI,KAAK,CAAC;QACb,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC;QACtC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CACJ,CAAC;AAUF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,+BAA+B,EACxC,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,gBAAgB,GACzB,2BAA2B,CAmH7B"}
+{"version":3,"file":"openai-chat-request-builder.d.ts","sourceRoot":"","sources":["../src/openai-chat-request-builder.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,2BAA2B,CAAC;AAOnC,MAAM,WAAW,+BAAgC,SAAQ,uBAAuB;IAC9E,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,yFAAyF;AACzF,MAAM,MAAM,qBAAqB,GAAG,0BAA0B,CAAC;AAE/D,KAAK,gBAAgB,GAAG;IACtB,IAAI,CAAC,OAAO,EAAE;QACZ,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC;QACtC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI,CAAC;IACT,KAAK,IAAI,KAAK,CAAC;QACb,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC;QACtC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CACJ,CAAC;AAUF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,+BAA+B,EACxC,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,gBAAgB,GACzB,2BAA2B,CA+H7B"}

package/esm/openai-chat-request-builder.js

@@ -1,5 +1,6 @@
 import { readProviderOptions, toOpenAICompatibleMessages, toOpenAICompatibleTools, unwrapToolInputSchema, } from "veryfront/provider/shared";
 import { rejectsOpenAISamplingParams, resolveOpenAIReasoningConfig, } from "./openai-reasoning-models.js";
+import { defineOpenAIProviderOptions } from "./openai-provider-options.js";
 function isNativeOpenAIModel(modelId) {
     return /^(gpt-|o[134](-|$)|chatgpt-)/.test(modelId);
 }
@@ -12,6 +13,7 @@ export function buildOpenAIChatRequest(modelId, providerName, options, stream, w
     const samplingRejected = rejectsOpenAISamplingParams(modelId);
     const fixedSampling = isFixedSamplingModel(modelId);
     const dropSamplingParams = reasoningEnabled || samplingRejected || fixedSampling;
+    const messages = toOpenAICompatibleMessages(options.prompt);
     // OpenAI Chat Completions has no top_k surface.
     if (options.topK !== undefined) {
         warnings.push({
@@ -47,7 +49,7 @@ export function buildOpenAIChatRequest(modelId, providerName, options, stream, w
     }
     const body = {
         model: modelId,
-        messages: toOpenAICompatibleMessages(options.prompt),
+        messages,
         ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
         ...(options.maxOutputTokens !== undefined
             ? isNativeOpenAIModel(modelId)
@@ -59,7 +61,7 @@ export function buildOpenAIChatRequest(modelId, providerName, options, stream, w
             : {}),
         ...(!dropSamplingParams && options.topP !== undefined ? { top_p: options.topP } : {}),
         ...(options.stopSequences && options.stopSequences.length > 0
-            ? { stop: options.stopSequences }
+            ? { stop: [...options.stopSequences] }
             : {}),
         ...(toOpenAICompatibleTools(options.tools)
             ? { tools: toOpenAICompatibleTools(options.tools) }
@@ -109,9 +111,21 @@ export function buildOpenAIChatRequest(modelId, providerName, options, stream, w
     ];
     const providerOpts = {};
     for (const bucketName of bucketNames) {
-        Object.assign(providerOpts, normalizeNativeMaxTokens(readProviderOptions(options.providerOptions, bucketName), modelId));
+        defineOpenAIProviderOptions(providerOpts, normalizeNativeMaxTokens(readProviderOptions(options.providerOptions, bucketName), modelId));
+    }
+    defineOpenAIProviderOptions(body, providerOpts);
+    // Provider-native options may tune request behavior, but they must not
+    // replace the runtime-owned transport mode, model, or conversation.
+    body.model = modelId;
+    body.messages = messages;
+    if (stream) {
+        body.stream = true;
+        body.stream_options = { include_usage: true };
+    }
+    else {
+        delete body.stream;
+        delete body.stream_options;
     }
-    Object.assign(body, providerOpts);
     return body;
 }
 /** Normalizes max_tokens to max_completion_tokens for native OpenAI models. */

package/esm/openai-chat-stream.d.ts

@@ -1,2 +1,9 @@
-export declare function streamOpenAICompatibleParts(stream: ReadableStream<Uint8Array>): AsyncIterable<unknown>;
+type OpenAICompatibleProviderKind = "openai" | "mistral" | "moonshotai";
+type OpenAIChatStreamContext = {
+    providerKind?: OpenAICompatibleProviderKind;
+    providerLabel?: string;
+};
+export declare const MAX_OPENAI_STREAM_TOOL_CALLS = 1024;
+export declare function streamOpenAICompatibleParts(stream: ReadableStream<Uint8Array>, context?: OpenAIChatStreamContext): AsyncIterable<unknown>;
+export {};
 //# sourceMappingURL=openai-chat-stream.d.ts.map

package/esm/openai-chat-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-chat-stream.d.ts","sourceRoot":"","sources":["../src/openai-chat-stream.ts"],"names":[],"mappings":"AAwIA,wBAAuB,2BAA2B,CAChD,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GACjC,aAAa,CAAC,OAAO,CAAC,CAsJxB"}
+{"version":3,"file":"openai-chat-stream.d.ts","sourceRoot":"","sources":["../src/openai-chat-stream.ts"],"names":[],"mappings":"AA2BA,KAAK,4BAA4B,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;AAExE,KAAK,uBAAuB,GAAG;IAC7B,YAAY,CAAC,EAAE,4BAA4B,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AASF,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AA4KlD,wBAAuB,2BAA2B,CAChD,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,GAAE,uBAA4B,GACpC,aAAa,CAAC,OAAO,CAAC,CAuVxB"}