@warlock.js/ai-openai 5.31.0 → 5.33.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `@warlock.js/ai-openai` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.33.0 - 2026-10-19
+
+### Changed
+
+- Lockstep release; package APIs are unchanged.
+
+## 5.32.0 - 2026-10-18
+
+### Changed
+
+- Remove the unreleased Kimi/Moonshot `$web_search` builtin echo path; reject declarations of the builtin retiring on 20 October 2026 and document migration to standalone REST tools.
+
+- Pin the package development compiler to TypeScript 7.0.2 and use explicit Node types and source roots with supported module resolution.
+
+### Fixed
+
+- Verified that Responses native token counting preserves the shared unsupported-count signal for `countInputTokens` estimation while authentication errors propagate.
+
+### Added
+
+- Export `kimiSearchTool()` (Basic/Pro), `kimiFetchTool()` and verified `KIMI_SERVER_TOOL_PRICING`: authenticated, cancellable first-party REST calls with compact results, mapped errors, no automatic retries, and billable response usage/costs aggregated into agent reports.
+
+- Retain Responses hosted output/actions/sources and count web-search calls without double-counting stream snapshots. Export opt-in `OPENAI_SERVER_TOOL_PRICING`. Support typed Qwen/DashScope `enableSearch` flags.
+
 ## 5.31.0 - 2026-10-18
 
 ### Fixed

package/cjs/index.cjs

@@ -20,7 +20,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
@@ -144,6 +144,10 @@ const OPENAI_MODEL_PRICING = {
 function openAIPricingFor(modelName) {
 	return OPENAI_MODEL_PRICING[modelName];
 }
+/** USD per request for web_search (NOT non-reasoning web_search_preview).
+* Search content tokens are additional; preview variants can have other rates.
+* https://developers.openai.com/api/docs/pricing#built-in-tools — verified 2026-10-18. */
+const OPENAI_SERVER_TOOL_PRICING = { webSearch: .01 };
 
 //#endregion
 //#region ../../packages/ai-openai/src/utils/build-usage.ts
@@ -413,7 +417,7 @@ function mapFinishReason(raw) {
 * Groq and DeepSeek cache automatically and document no request hint, so
 * they receive nothing (checked 2026-10-17).
 */
-const PROMPT_CACHE_KEY_PROVIDERS = new Set([
+const PROMPT_CACHE_KEY_PROVIDERS = /* @__PURE__ */ new Set([
 	"openai",
 	"xai",
 	"mistral"
@@ -565,7 +569,7 @@ function pickReplayableReasoning(items) {
 	return items.filter((item) => typeof item.encrypted_content === "string" && item.encrypted_content !== "");
 }
 /** Output item types that may follow a replayed reasoning item. */
-const REPLAY_SAFE_FOLLOWERS = new Set(["function_call", "message"]);
+const REPLAY_SAFE_FOLLOWERS = /* @__PURE__ */ new Set(["function_call", "message"]);
 /**
 * The reasoning items of a turn that are safe to replay, in order.
 *
@@ -1238,7 +1242,7 @@ var OpenAIImageModel = class {
 
 //#endregion
 //#region ../../packages/ai-openai/src/provider-options.ts
-const RESERVED_FIELDS = new Set([
+const RESERVED_FIELDS = /* @__PURE__ */ new Set([
 	"model",
 	"messages",
 	"input",
@@ -1280,6 +1284,13 @@ function isPlainObject(value) {
 	const prototype = Object.getPrototypeOf(value);
 	return prototype === Object.prototype || prototype === null;
 }
+function compatibleSearchParams(provider, options) {
+	if (provider !== "qwen" && provider !== "dashscope") return {};
+	const value = options?.providerOptions?.[provider]?.enableSearch;
+	if (value === void 0) return {};
+	if (typeof value !== "boolean") throw new _warlock_js_ai.InvalidRequestError(`providerOptions.${provider}.enableSearch must be a boolean`);
+	return { enable_search: value };
+}
 
 //#endregion
 //#region ../../packages/ai-openai/src/known-reasoning-models.ts
@@ -1445,6 +1456,7 @@ var OpenAIModel = class {
 		try {
 			response = await this.client.chat.completions.create(mergeProviderBody({
 				model: this.name,
+				...compatibleSearchParams(this.provider, options),
 				messages: toOpenAIMessages(messages, this.promptCacheBreakpoints(options)),
 				...this.buildSamplingParams(options),
 				...buildPromptCacheParams(this.provider, this.config),
@@ -1501,6 +1513,7 @@ var OpenAIModel = class {
 		try {
 			stream = await this.client.chat.completions.create(mergeProviderBody({
 				model: this.name,
+				...compatibleSearchParams(this.provider, options),
 				messages: toOpenAIMessages(messages, this.promptCacheBreakpoints(options)),
 				...this.buildSamplingParams(options),
 				...buildPromptCacheParams(this.provider, this.config),
@@ -1610,6 +1623,11 @@ var OpenAIModel = class {
 			model: this.name,
 			logger: this.logger
 		});
+		if ((this.provider === "moonshot" || this.provider === "kimi") && definitions.some((definition) => {
+			const fn = definition.function;
+			return definition.type === "builtin_function" && typeof fn === "object" && fn !== null && "name" in fn && fn.name === "$web_search";
+		})) throw new _warlock_js_ai.InvalidRequestError("Kimi's builtin $web_search retires on 20 October 2026. Use kimiSearchTool() / kimiFetchTool() from @warlock.js/ai-openai.");
+		if (this.provider === "xai" && definitions.some((definition) => definition.type === "web_search" || definition.type === "x_search")) throw new _warlock_js_ai.InvalidRequestError("xAI native web_search / x_search requires POST /v1/responses. XaiSDK currently supports Chat Completions only; use xAI's Responses API with the vendor SDK for native search.");
 		const mapped = [...toOpenAITools(tools) ?? [], ...definitions];
 		return mapped.length > 0 ? { tools: mapped } : {};
 	}
@@ -1759,6 +1777,24 @@ function readReasoningDelta(delta) {
 	}
 }
 
+//#endregion
+//#region ../../packages/ai-openai/src/utils/hosted-output.ts
+/** Installed openai 7.23.0 ResponseFunctionWebSearch (action includes search/open_page/find).
+* https://developers.openai.com/api/docs/guides/tools-web-search
+* Count output items, never URLs, sources, answer text, or function calls.
+* Fees and search content tokens are separate; preview pricing varies:
+* https://developers.openai.com/api/docs/pricing#built-in-tools */
+function hostedOutput(usage, output, pricing) {
+	const hosted = output.filter((item) => item.type !== "message" && item.type !== "reasoning" && item.type !== "function_call");
+	const searches = hosted.filter((item) => item.type === "web_search_call");
+	if (searches.length) usage.serverToolUse = {
+		...usage.serverToolUse,
+		webSearchRequests: searches.length
+	};
+	(0, _warlock_js_ai.attachCost)(usage, pricing);
+	return hosted.length ? { openai: { output: hosted } } : void 0;
+}
+
 //#endregion
 //#region ../../packages/ai-openai/src/responses-model.ts
 const LOG_MODULE$2 = "ai.openai";
@@ -1767,7 +1803,7 @@ const LOG_MODULE$2 = "ai.openai";
 * (installed SDK `ResponseOutputItem` union). The adapter maps only
 * `function_call` to a neutral tool call, so these fail closed.
 */
-const CLIENT_RUN_ITEM_TYPES = new Set([
+const CLIENT_RUN_ITEM_TYPES = /* @__PURE__ */ new Set([
 	"computer_call",
 	"custom_tool_call",
 	"local_shell_call",
@@ -1808,7 +1844,8 @@ const CLIENT_RUN_ITEM_TYPES = new Set([
 *
 * **Provider-defined tools.** `ai.providerTool({ provider: "openai" })`
 * definitions are appended to `tools` verbatim. Hosted tools run inside the
-* response; their output items (`web_search_call`, …) are not replayed
+* response; their output items (`web_search_call`, …) are retained in
+* `providerMetadata.openai.output` for inspection and are not replayed
 * (with `store: false` the next turn only needs the answer text), and a
 * reasoning item that led into one is not replayed either (see
 * `pickTurnReasoning`).
@@ -1863,6 +1900,7 @@ var OpenAIResponsesModel = class {
 			hasToolCalls: toolCalls !== void 0
 		});
 		const usage = this.extractUsage(response.usage);
+		const providerMetadata = hostedOutput(usage, output, this.pricing);
 		this.logger.debug(LOG_MODULE$2, "response", "call to responses.create succeeded", {
 			finishReason,
 			usage
@@ -1871,6 +1909,7 @@ var OpenAIResponsesModel = class {
 			content,
 			finishReason,
 			usage,
+			...providerMetadata ? { providerMetadata } : {},
 			...toolCalls ? { toolCalls } : {}
 		};
 	}
@@ -2004,6 +2043,8 @@ var OpenAIResponsesModel = class {
 			hasToolCalls: toolCalls.length > 0
 		});
 		const usage = this.extractUsage(terminal.usage);
+		const output = terminal.output?.length ? terminal.output : outputItems;
+		const providerMetadata = hostedOutput(usage, output, this.pricing);
 		this.logger.debug(LOG_MODULE$2, "response", "Streaming call to responses.create succeeded", {
 			finishReason,
 			usage
@@ -2011,7 +2052,8 @@ var OpenAIResponsesModel = class {
 		yield {
 			type: "done",
 			finishReason,
-			usage
+			usage,
+			...providerMetadata ? { providerMetadata } : {}
 		};
 	}
 	/**
@@ -2038,7 +2080,7 @@ var OpenAIResponsesModel = class {
 			...instructions !== void 0 ? { instructions } : {},
 			input,
 			store: false,
-			include: ["reasoning.encrypted_content"],
+			include: ["reasoning.encrypted_content", ...tools?.some((tool) => tool.type === "web_search" || tool.type === "web_search_2025_08_26" || tool.type === "web_search_preview" || tool.type === "web_search_preview_2025_03_11") ? ["web_search_call.action.sources"] : []],
 			...maxTokens !== void 0 ? { max_output_tokens: maxTokens } : {},
 			...!this.capabilities.reasoning && temperature !== void 0 ? { temperature } : {},
 			...tools ? { tools } : {},
@@ -2489,11 +2531,265 @@ var OpenAISDK = class {
 };
 
 //#endregion
+//#region ../../packages/ai-openai/src/kimi-tools.ts
+/** USD per billable REST request, verified 2026-10-18:
+* https://platform.kimi.ai/docs/pricing/websearch
+* HTTP 200 + nonempty search_results / nonblank markdown only. Taxes excluded.
+* Namespaced rates avoid charging the generic counters a second time. */
+const KIMI_SERVER_TOOL_PRICING = Object.freeze({
+	kimiSearchRequests: .002,
+	kimiSearchProRequests: .003,
+	kimiFetchRequests: .002
+});
+/** Standalone first-party REST search, registered as an ordinary client function tool.
+* Wire contract: https://platform.kimi.ai/docs/api/tools-search and tools-search-pro.
+* Reuse the API key / baseURL configuration passed to OpenAISDK; the default URL
+* here is Moonshot, independent of the model used by the agent. */
+function kimiSearchTool(options) {
+	const mode = options.mode ?? "basic";
+	if (mode !== "basic" && mode !== "pro") throw new _warlock_js_ai.InvalidRequestError("Invalid Kimi search mode.");
+	const limit = integer(options.limit ?? 5, 1, 20, "limit");
+	const timeout = integer(options.timeoutSeconds ?? 30, 1, 60, "timeoutSeconds");
+	if (mode === "basic" && (options.sites !== void 0 || options.timeWindow !== void 0)) throw new _warlock_js_ai.InvalidRequestError("Kimi sites and timeWindow require mode: pro.");
+	if (mode === "pro" && options.includeContent !== void 0) throw new _warlock_js_ai.InvalidRequestError("Kimi includeContent is available only in basic mode.");
+	if (options.sites && (options.sites.length > 5 || options.sites.some((site) => !site || /[\s()]/u.test(site)))) throw new _warlock_js_ai.InvalidRequestError("Kimi sites accepts at most five nonempty sites without whitespace or parentheses.");
+	const maxChars = contentLimit(options);
+	const client = createClient(options);
+	const counter = mode === "pro" ? "kimiSearchProRequests" : "kimiSearchRequests";
+	return meteredTool({
+		name: mode === "pro" ? "kimi_search_pro" : "kimi_search",
+		description: "Search the web with Kimi and return cited sources and relevant text.",
+		input: stringInput("query"),
+		async execute({ query }, ctx, record) {
+			const body = {
+				text_query: query,
+				limit,
+				timeout_seconds: timeout,
+				...mode === "basic" ? { include_content: options.includeContent ?? false } : {
+					...options.sites !== void 0 ? { sites: options.sites } : {},
+					...options.timeWindow !== void 0 ? { time_window: options.timeWindow } : {}
+				}
+			};
+			const raw = await request(client, mode === "pro" ? "/tools/search_pro" : "/tools/search", body, ctx);
+			if (!isObject(raw.data) || !Array.isArray(raw.data.search_results)) throw new _warlock_js_ai.ProviderError("Kimi returned invalid search_results.");
+			record(raw.status === 200 && raw.data.search_results.length > 0);
+			const budget = textBudget(maxChars);
+			return {
+				results: raw.data.search_results.slice(0, limit).map((value) => {
+					if (!isObject(value)) throw new _warlock_js_ai.ProviderError("Kimi returned an invalid search result.");
+					const result = {
+						title: stringValue(value.title),
+						url: stringValue(value.url),
+						snippet: budget.take(stringValue(value.snippet)),
+						siteName: stringValue(value.site_name),
+						date: stringValue(value.date),
+						authority: stringValue(value.authority)
+					};
+					if (mode === "basic" && options.includeContent) result.text = budget.take(stringValue(value.text));
+					if (mode === "pro") {
+						if (!Array.isArray(value.chunks)) throw new _warlock_js_ai.ProviderError("Kimi returned invalid search chunks.");
+						result.chunks = value.chunks.map((chunk) => {
+							if (!isObject(chunk) || typeof chunk.score !== "number" || !Number.isFinite(chunk.score)) throw new _warlock_js_ai.ProviderError("Kimi returned an invalid search chunk.");
+							return {
+								text: budget.take(stringValue(chunk.text)),
+								score: chunk.score
+							};
+						}).filter((chunk) => chunk.text.length > 0);
+					}
+					return result;
+				}),
+				truncated: budget.truncated || raw.data.search_results.length > limit
+			};
+		}
+	}, counter, options.pricing);
+}
+/** First-party URL-to-Markdown REST tool.
+* https://platform.kimi.ai/docs/api/tools-fetch — only http/https inputs. */
+function kimiFetchTool(options) {
+	const client = createClient(options);
+	const maxChars = contentLimit(options);
+	return meteredTool({
+		name: "kimi_fetch",
+		description: "Read a web page with Kimi and return its title, URL and Markdown body.",
+		input: stringInput("url"),
+		async execute({ url }, ctx, record) {
+			let parsed;
+			try {
+				parsed = new URL(url);
+			} catch {
+				throw new _warlock_js_ai.InvalidRequestError("Kimi fetch requires an http/https URL.");
+			}
+			if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new _warlock_js_ai.InvalidRequestError("Kimi fetch requires an http/https URL.");
+			const raw = await request(client, "/tools/fetch", { url }, ctx);
+			if (!isObject(raw.data) || typeof raw.data.markdown !== "string") throw new _warlock_js_ai.ProviderError("Kimi returned invalid fetch content.");
+			record(raw.status === 200 && raw.data.markdown.trim().length > 0);
+			return {
+				url: stringValue(raw.data.url),
+				title: stringValue(raw.data.title),
+				markdown: raw.data.markdown.slice(0, maxChars),
+				truncated: raw.data.markdown.length > maxChars
+			};
+		}
+	}, "kimiFetchRequests", options.pricing);
+}
+function createClient(options) {
+	const { apiKey, baseURL, fetch, timeout, defaultHeaders } = options;
+	if (!apiKey) throw new _warlock_js_ai.ProviderAuthError("Kimi tools require an explicitly configured API key.");
+	return new openai.default({
+		apiKey,
+		baseURL: baseURL ?? "https://api.moonshot.ai/v1",
+		fetch,
+		timeout,
+		defaultHeaders,
+		maxRetries: 0
+	});
+}
+async function request(client, path, body, ctx) {
+	try {
+		ctx?.signal?.throwIfAborted();
+		const response = await client.post(path, {
+			body,
+			signal: ctx?.signal
+		}).withResponse();
+		return {
+			data: response.data,
+			status: response.response.status
+		};
+	} catch (thrown) {
+		if (ctx?.signal?.aborted) throw new _warlock_js_ai.AgentCancelledError("Kimi tool request cancelled.", { cause: thrown });
+		if (thrown instanceof openai.APIError) {
+			const context = {
+				status: thrown.status,
+				type: thrown.type,
+				requestId: thrown.headers?.get("x-msh-track-id")
+			};
+			if (thrown.status === 408 || thrown.status === 504) throw new _warlock_js_ai.ProviderTimeoutError(thrown.message, {
+				cause: thrown,
+				context
+			});
+			if (thrown.status === 429) {
+				const retry = Number(thrown.headers?.get("retry-after") ?? NaN);
+				throw new _warlock_js_ai.ProviderRateLimitError(thrown.message, {
+					cause: thrown,
+					context,
+					retryAfter: Number.isFinite(retry) && retry >= 0 ? retry * 1e3 : void 0
+				});
+			}
+			if (thrown.status === 403 && !thrown.type) throw new _warlock_js_ai.ProviderAuthError(thrown.message, {
+				cause: thrown,
+				context
+			});
+		}
+		throw wrapOpenAIError(thrown);
+	}
+}
+/** Each invoke owns its ledger, including concurrent calls and post-response failures.
+* ToolContract.invoke is the existing accounting boundary used by agents/reports. */
+function meteredTool(config, counter, prices = KIMI_SERVER_TOOL_PRICING) {
+	const rate = prices[counter];
+	if (rate !== void 0 && (!Number.isFinite(rate) || rate < 0)) throw new _warlock_js_ai.InvalidRequestError("Kimi per-call pricing must be finite and nonnegative.");
+	return {
+		...(0, _warlock_js_ai.tool)({
+			...config,
+			execute: (input, ctx) => config.execute(input, ctx, () => {})
+		}),
+		async invoke(input, ctx) {
+			let usage = {
+				input: 0,
+				output: 0,
+				total: 0
+			};
+			const result = await (0, _warlock_js_ai.tool)({
+				...config,
+				execute: (validated, context) => config.execute(validated, context, (billable) => {
+					const count = billable ? 1 : 0;
+					usage = {
+						input: 0,
+						output: 0,
+						total: 0,
+						serverToolUse: {
+							[counter]: count,
+							[counter === "kimiFetchRequests" ? "webFetchRequests" : "webSearchRequests"]: count
+						}
+					};
+					if (rate !== void 0) usage.cost = (0, _warlock_js_ai.computeCost)(usage, {
+						input: 0,
+						output: 0,
+						serverTools: { [counter]: rate }
+					});
+				})
+			}).invoke(input, ctx);
+			return {
+				...result,
+				usage,
+				report: {
+					...result.report,
+					usage
+				}
+			};
+		}
+	};
+}
+function integer(value, min, max, name) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new _warlock_js_ai.InvalidRequestError(`Kimi ${name} must be an integer from ${min} to ${max}.`);
+	return value;
+}
+function contentLimit(options) {
+	return integer(options.maxContentChars ?? 12e3, 1, Number.MAX_SAFE_INTEGER, "maxContentChars");
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringValue(value) {
+	if (typeof value !== "string") throw new _warlock_js_ai.ProviderError("Kimi returned an invalid text field.");
+	return value;
+}
+function textBudget(max) {
+	return {
+		truncated: false,
+		take(text) {
+			const result = text.slice(0, max);
+			if (text.length > max) this.truncated = true;
+			max -= result.length;
+			return result;
+		}
+	};
+}
+function stringInput(key) {
+	return {
+		jsonSchema: {
+			type: "object",
+			properties: { [key]: {
+				type: "string",
+				minLength: 1
+			} },
+			required: [key],
+			additionalProperties: false
+		},
+		"~standard": {
+			version: 1,
+			vendor: "kimi",
+			validate(value) {
+				if (!isObject(value) || typeof value[key] !== "string" || !value[key].trim()) return { issues: [{
+					message: `${key} must be a nonempty string`,
+					path: [key]
+				}] };
+				return { value: { [key]: value[key] } };
+			}
+		}
+	};
+}
+
+//#endregion
+exports.KIMI_SERVER_TOOL_PRICING = KIMI_SERVER_TOOL_PRICING;
 exports.OPENAI_MODEL_PRICING = OPENAI_MODEL_PRICING;
+exports.OPENAI_SERVER_TOOL_PRICING = OPENAI_SERVER_TOOL_PRICING;
 exports.OpenAIEmbedder = OpenAIEmbedder;
 exports.OpenAIImageModel = OpenAIImageModel;
 exports.OpenAISDK = OpenAISDK;
 exports.OpenAISpeechModel = OpenAISpeechModel;
 exports.OpenAITranscriptionModel = OpenAITranscriptionModel;
+exports.kimiFetchTool = kimiFetchTool;
+exports.kimiSearchTool = kimiSearchTool;
 exports.openAIPricingFor = openAIPricingFor;
 //# sourceMappingURL=index.cjs.map