webseek 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -41,6 +41,24 @@ interface Citation {
   startIndex?: number;
   endIndex?: number;
 }
+/** What a search consumed. Token counts are absent for SERP providers. */
+interface SearchUsage {
+  /** Prompt tokens, including cached ones and fetched search content. */
+  inputTokens?: number;
+  /** The part of `inputTokens` served from the prompt cache. */
+  cachedInputTokens?: number;
+  /** Generated tokens, including reasoning/thinking tokens. */
+  outputTokens?: number;
+  totalTokens?: number;
+  /** Searches the provider ran (web search tool calls, grounding queries, or SERP requests). */
+  searchCalls: number;
+}
+/** Estimated list-price cost of a search in USD (free tiers not applied). */
+interface SearchCost {
+  totalUsd: number;
+  tokensUsd: number;
+  searchUsd: number;
+}
 /** The normalized result shape returned by every provider. */
 interface NormalizedSearchResult {
   provider: ProviderName;
@@ -53,6 +71,12 @@ interface NormalizedSearchResult {
   citations: Citation[];
   /** Queries the provider actually ran (grounded providers). */
   searchQueries: string[];
+  /** The model that served the search (grounded providers). */
+  model?: string;
+  /** Tokens and searches consumed (always set by the built-in providers). */
+  usage?: SearchUsage;
+  /** Estimated cost; absent when the model's price is unknown. */
+  cost?: SearchCost;
   /** The provider's raw response, included only when requested. */
   raw?: unknown;
 }
@@ -75,8 +99,8 @@ interface SearchProvider {
 }
 //#endregion
 //#region src/lib/search.d.ts
-declare const PROVIDER_NAMES: readonly ["openai", "google", "gemini"];
-declare const GEMINI_BACKENDS: readonly ["gemini-api", "vertex-express"];
+export declare const PROVIDER_NAMES: readonly ["openai", "google", "gemini"];
+export declare const GEMINI_BACKENDS: readonly ["gemini-api", "vertex-express"];
 interface RunSearchParams {
   provider: ProviderName;
   query: string;
@@ -87,7 +111,28 @@ interface RunSearchParams {
   env?: Env;
   fetchImpl?: typeof fetch;
 }
-declare function runSearch(params: RunSearchParams): Promise<NormalizedSearchResult>;
+export declare function runSearch(params: RunSearchParams): Promise<NormalizedSearchResult>;
+//#endregion
+//#region src/pricing/pricing.d.ts
+interface EstimateCostParams {
+  provider: ProviderName;
+  /** The model that served the search (ignored for SERP providers). */
+  model?: string;
+  /**
+   * Priced instead when `model` is not in the table — typically the requested
+   * model, since the served id may be a snapshot or variant the table lacks.
+   */
+  fallbackModel?: string;
+  usage: SearchUsage;
+  /** Price as of this moment (rates can change on a set date); defaults to now. */
+  now?: Date;
+}
+/**
+ * Estimate what a search cost at list price, or `undefined` when it cannot be
+ * priced: the model is not in this table (e.g. newer than it), or an LLM-backed
+ * provider reported no token counts (a search-fee-only figure would understate).
+ */
+export declare function estimateCost(params: EstimateCostParams): SearchCost | undefined;
 //#endregion
 //#region src/utils/error.d.ts
 /**
@@ -104,7 +149,7 @@ interface WebseekErrorOptions {
   message: string;
   cause?: unknown;
 }
-declare class WebseekError extends Error {
+export declare class WebseekError extends Error {
   readonly code: WebseekErrorCode;
   constructor(options: WebseekErrorOptions);
 }
@@ -112,12 +157,12 @@ declare class WebseekError extends Error {
  * Map a thrown value to a process exit code: `2` for usage mistakes, `1` for
  * any other failure.
  */
-declare function errorExitCode(error: unknown): number;
+export declare function errorExitCode(error: unknown): number;
 /** Render any thrown value into a single-line, user-facing message. */
-declare function formatError(error: unknown): string;
+export declare function formatError(error: unknown): string;
 //#endregion
 //#region src/mcp/tools.d.ts
-declare const webSearchInputShape: {
+export declare const webSearchInputShape: {
   query: z.ZodString;
   provider: z.ZodEnum<{
     gemini: "gemini";
@@ -161,6 +206,8 @@ interface CreateWebSearchToolParams {
   env?: Env;
   /** Injectable for tests; defaults to the global fetch. */
   fetchImpl?: typeof fetch;
+  /** Called with every successful result before it is returned (e.g. to log usage). */
+  onResult?: (result: NormalizedSearchResult) => Promise<void> | void;
 }
 interface WebSearchTool {
   name: string;
@@ -171,6 +218,6 @@ interface WebSearchTool {
   };
   handler: (args: WebSearchArgs) => Promise<ToolResult>;
 }
-declare function createWebSearchTool(params?: CreateWebSearchToolParams): WebSearchTool;
+export declare function createWebSearchTool(params?: CreateWebSearchToolParams): WebSearchTool;
 //#endregion
-export { type Citation, type CreateWebSearchToolParams, type Env, GEMINI_BACKENDS, type GeminiBackend, type NormalizedSearchResult, PROVIDER_NAMES, type ProviderName, type RunSearchParams, type SearchParams, type SearchProvider, type SearchResultItem, type ToolResult, type WebSearchArgs, type WebSearchTool, WebseekError, type WebseekErrorCode, type WebseekErrorOptions, createWebSearchTool, errorExitCode, formatError, runSearch, webSearchInputShape };
+export type { Citation, CreateWebSearchToolParams, Env, EstimateCostParams, GeminiBackend, NormalizedSearchResult, ProviderName, RunSearchParams, SearchCost, SearchParams, SearchProvider, SearchResultItem, SearchUsage, ToolResult, WebSearchArgs, WebSearchTool, WebseekErrorCode, WebseekErrorOptions };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { c as runSearch, d as formatError, i as PROVIDER_NAMES, l as WebseekError, n as webSearchInputShape, r as GEMINI_BACKENDS, t as createWebSearchTool, u as errorExitCode } from "./tools-DBF9nCIs.mjs";
-export { GEMINI_BACKENDS, PROVIDER_NAMES, WebseekError, createWebSearchTool, errorExitCode, formatError, runSearch, webSearchInputShape };
+import { c as runSearch, d as errorExitCode, f as formatError, i as PROVIDER_NAMES, l as estimateCost, n as webSearchInputShape, r as GEMINI_BACKENDS, t as createWebSearchTool, u as WebseekError } from "./tools-1ZllUYBx.mjs";
+export { GEMINI_BACKENDS, PROVIDER_NAMES, WebseekError, createWebSearchTool, errorExitCode, estimateCost, formatError, runSearch, webSearchInputShape };

package/dist/{tools-DBF9nCIs.mjs → tools-1ZllUYBx.mjs}

@@ -99,6 +99,183 @@ function resolveGeminiConfig(params) {
 	};
 }
 //#endregion
+//#region src/pricing/pricing.ts
+/** OpenAI's `web_search` tool: $10 per 1k calls; search content tokens bill at model rates. */
+const OPENAI_SEARCH_PER_1K = 10;
+const OPENAI_PRICES = {
+	"gpt-5.5": openai({
+		input: 5,
+		cachedInput: .5,
+		output: 30
+	}),
+	"gpt-5.4": openai({
+		input: 2.5,
+		cachedInput: .25,
+		output: 15
+	}),
+	"gpt-5": openai({
+		input: 1.25,
+		cachedInput: .125,
+		output: 10
+	}),
+	"gpt-5-mini": openai({
+		input: .25,
+		cachedInput: .025,
+		output: 2
+	}),
+	"gpt-5-nano": openai({
+		input: .05,
+		cachedInput: .005,
+		output: .4
+	}),
+	"gpt-4.1": openai({
+		input: 2,
+		cachedInput: .5,
+		output: 8
+	}),
+	"gpt-4o": openai({
+		input: 2.5,
+		cachedInput: 1.25,
+		output: 10
+	}),
+	"gpt-4o-mini": openai({
+		input: .15,
+		cachedInput: .075,
+		output: .6
+	})
+};
+/**
+* Gemini 3.x: "$14 per 1,000 requests", read as one charge per search query the
+* model ran (each `webSearchQueries` entry), not per prompt.
+*/
+const GEMINI_3_SEARCH_PER_1K = 14;
+/** Gemini 2.5 bills each grounded prompt, however many queries it ran ($35 per 1k). */
+const GEMINI_2_5_SEARCH_PER_1K = 35;
+const GEMINI_3_FLASH = {
+	rates: {
+		input: .75,
+		cachedInput: .075,
+		output: 3.75
+	},
+	next: {
+		from: "2027-01-01",
+		rates: {
+			input: 1.5,
+			cachedInput: .15,
+			output: 7.5
+		}
+	},
+	searchPer1k: GEMINI_3_SEARCH_PER_1K
+};
+const GEMINI_PRICES = {
+	"gemini-3.8-flash": GEMINI_3_FLASH,
+	"gemini-3.7-flash": GEMINI_3_FLASH,
+	"gemini-3.6-flash": GEMINI_3_FLASH,
+	"gemini-3-flash-preview": GEMINI_3_FLASH,
+	"gemini-3.5-flash": gemini3({
+		input: 1.5,
+		cachedInput: .15,
+		output: 9
+	}),
+	"gemini-3.5-flash-lite": gemini3({
+		input: .3,
+		cachedInput: .03,
+		output: 2.5
+	}),
+	"gemini-3.1-flash-lite": gemini3({
+		input: .25,
+		cachedInput: .025,
+		output: 1.5
+	}),
+	"gemini-3.1-pro-preview": gemini3({
+		input: 2,
+		cachedInput: .2,
+		output: 12
+	}),
+	"gemini-2.5-pro": gemini25({
+		input: 1.25,
+		cachedInput: .125,
+		output: 10
+	}),
+	"gemini-2.5-flash": gemini25({
+		input: .3,
+		cachedInput: .03,
+		output: 2.5
+	}),
+	"gemini-2.5-flash-lite": gemini25({
+		input: .1,
+		cachedInput: .01,
+		output: .4
+	})
+};
+/** Google Custom Search: $5 per 1k queries (each paginated request is a query). */
+const GOOGLE_CSE_PER_1K = 5;
+function openai(rates) {
+	return {
+		rates,
+		searchPer1k: OPENAI_SEARCH_PER_1K
+	};
+}
+function gemini3(rates) {
+	return {
+		rates,
+		searchPer1k: GEMINI_3_SEARCH_PER_1K
+	};
+}
+function gemini25(rates) {
+	return {
+		rates,
+		searchPer1k: GEMINI_2_5_SEARCH_PER_1K,
+		searchPerPrompt: true
+	};
+}
+/**
+* Estimate what a search cost at list price, or `undefined` when it cannot be
+* priced: the model is not in this table (e.g. newer than it), or an LLM-backed
+* provider reported no token counts (a search-fee-only figure would understate).
+*/
+function estimateCost(params) {
+	const { usage } = params;
+	if (params.provider === "google") {
+		const searchUsd = usage.searchCalls * GOOGLE_CSE_PER_1K / 1e3;
+		return {
+			totalUsd: searchUsd,
+			tokensUsd: 0,
+			searchUsd
+		};
+	}
+	const table = params.provider === "openai" ? OPENAI_PRICES : GEMINI_PRICES;
+	const price = [params.model, params.fallbackModel].filter((model) => model !== void 0).map((model) => lookupPrice({
+		table,
+		model
+	})).find((found) => found !== void 0);
+	if (price === void 0) return;
+	if (usage.inputTokens === void 0 && usage.outputTokens === void 0) return;
+	const rates = ratesAt({
+		price,
+		now: params.now ?? /* @__PURE__ */ new Date()
+	});
+	const inputTokens = usage.inputTokens ?? 0;
+	const cachedInputTokens = Math.min(usage.cachedInputTokens ?? 0, inputTokens);
+	const tokensUsd = ((inputTokens - cachedInputTokens) * rates.input + cachedInputTokens * rates.cachedInput + (usage.outputTokens ?? 0) * rates.output) / 1e6;
+	const searchUsd = (price.searchPerPrompt ? Math.min(usage.searchCalls, 1) : usage.searchCalls) * price.searchPer1k / 1e3;
+	return {
+		totalUsd: tokensUsd + searchUsd,
+		tokensUsd,
+		searchUsd
+	};
+}
+function lookupPrice(params) {
+	const { table } = params;
+	const id = params.model.replace(/^(?:.*\/)?models\//, "").replace(/-\d{4}-\d{2}-\d{2}$/, "").toLowerCase();
+	return Object.hasOwn(table, id) ? table[id] : void 0;
+}
+function ratesAt(params) {
+	const { price } = params;
+	if (price.next && params.now.toISOString().slice(0, 10) >= price.next.from) return price.next.rates;
+	return price.rates;
+}
+//#endregion
 //#region src/providers/gemini.ts
 /**
 * Gemini web search provider via "Grounding with Google Search".
@@ -151,8 +328,18 @@ const candidateSchema = z.looseObject({
 	content: z.looseObject({ parts: z.array(z.looseObject({ text: z.string().optional() })).optional() }).optional(),
 	groundingMetadata: groundingMetadataSchema.optional()
 });
+const usageMetadataSchema = z.looseObject({
+	promptTokenCount: z.number().optional(),
+	cachedContentTokenCount: z.number().optional(),
+	candidatesTokenCount: z.number().optional(),
+	thoughtsTokenCount: z.number().optional(),
+	toolUsePromptTokenCount: z.number().optional(),
+	totalTokenCount: z.number().optional()
+});
 const responseSchema$2 = z.looseObject({
 	candidates: z.array(candidateSchema).optional(),
+	usageMetadata: usageMetadataSchema.optional(),
+	modelVersion: z.string().optional(),
 	error: z.looseObject({ message: z.string().optional() }).optional()
 });
 function createGeminiProvider(params) {
@@ -183,6 +370,11 @@ function createGeminiProvider(params) {
 				body
 			});
 			const { answer, citations, searchQueries } = extract$1(parsed.data);
+			const servedModel = parsed.data.modelVersion ?? model;
+			const usage = toUsage$1({
+				usage: parsed.data.usageMetadata,
+				searchCalls: searchQueries.length
+			});
 			return {
 				provider: "gemini",
 				query: searchParams.query,
@@ -190,6 +382,14 @@ function createGeminiProvider(params) {
 				answer,
 				citations,
 				searchQueries,
+				model: servedModel,
+				usage,
+				cost: estimateCost({
+					provider: "gemini",
+					model: servedModel,
+					fallbackModel: model,
+					usage
+				}),
 				raw: searchParams.includeRaw ? body : void 0
 			};
 		}
@@ -208,6 +408,23 @@ function extract$1(data) {
 		searchQueries: metadata?.webSearchQueries ?? []
 	};
 }
+function toUsage$1(params) {
+	const { usage } = params;
+	if (usage === void 0) return { searchCalls: params.searchCalls };
+	const inputTokens = sumDefined([usage.promptTokenCount, usage.toolUsePromptTokenCount]);
+	const outputTokens = sumDefined([usage.candidatesTokenCount, usage.thoughtsTokenCount]);
+	return {
+		inputTokens,
+		cachedInputTokens: usage.cachedContentTokenCount,
+		outputTokens,
+		totalTokens: usage.totalTokenCount,
+		searchCalls: params.searchCalls
+	};
+}
+function sumDefined(values) {
+	const defined = values.filter((value) => value !== void 0);
+	return defined.length > 0 ? defined.reduce((total, value) => total + value, 0) : void 0;
+}
 function toError$2(params) {
 	const parsed = responseSchema$2.safeParse(params.body);
 	const message = (parsed.success ? parsed.data.error?.message : void 0) ?? `Gemini grounding request failed (HTTP ${params.status}).`;
@@ -262,6 +479,7 @@ function createGoogleCseProvider(params) {
 			const desired = clampDesired(searchParams.maxResults ?? MAX_PER_REQUEST);
 			const items = [];
 			let lastRaw;
+			let requests = 0;
 			for (let start = 1; start <= MAX_TOTAL_RESULTS && items.length < desired; start += MAX_PER_REQUEST) {
 				const num = Math.min(MAX_PER_REQUEST, desired - items.length);
 				const response = await fetchImpl(buildUrl({
@@ -270,6 +488,7 @@ function createGoogleCseProvider(params) {
 					start,
 					num
 				}));
+				requests += 1;
 				const body = await response.json().catch(() => void 0);
 				lastRaw = body;
 				const parsed = responseSchema$1.safeParse(body);
@@ -281,6 +500,7 @@ function createGoogleCseProvider(params) {
 				items.push(...page);
 				if (page.length < num) break;
 			}
+			const usage = { searchCalls: requests };
 			return {
 				provider: "google",
 				query: searchParams.query,
@@ -292,6 +512,11 @@ function createGoogleCseProvider(params) {
 				})),
 				citations: [],
 				searchQueries: [searchParams.query],
+				usage,
+				cost: estimateCost({
+					provider: "google",
+					usage
+				}),
 				raw: searchParams.includeRaw ? lastRaw : void 0
 			};
 		}
@@ -358,9 +583,17 @@ const outputItemSchema = z.looseObject({
 	content: z.array(contentSchema).optional(),
 	action: z.looseObject({ query: z.string().optional() }).optional()
 });
+const usageSchema = z.looseObject({
+	input_tokens: z.number().optional(),
+	input_tokens_details: z.looseObject({ cached_tokens: z.number().optional() }).nullish(),
+	output_tokens: z.number().optional(),
+	total_tokens: z.number().optional()
+});
 const responseSchema = z.looseObject({
 	output: z.array(outputItemSchema).optional(),
 	output_text: z.string().optional(),
+	model: z.string().optional(),
+	usage: usageSchema.nullish(),
 	error: z.looseObject({ message: z.string().optional() }).nullish()
 });
 function createOpenAIProvider(params) {
@@ -388,7 +621,12 @@ function createOpenAIProvider(params) {
 				status: response.status,
 				body
 			});
-			const { answer, citations, searchQueries } = extract(parsed.data);
+			const { answer, citations, searchQueries, searchCalls } = extract(parsed.data);
+			const servedModel = parsed.data.model ?? model;
+			const usage = toUsage({
+				usage: parsed.data.usage,
+				searchCalls
+			});
 			return {
 				provider: "openai",
 				query: searchParams.query,
@@ -396,6 +634,14 @@ function createOpenAIProvider(params) {
 				answer,
 				citations,
 				searchQueries,
+				model: servedModel,
+				usage,
+				cost: estimateCost({
+					provider: "openai",
+					model: servedModel,
+					fallbackModel: model,
+					usage
+				}),
 				raw: searchParams.includeRaw ? body : void 0
 			};
 		}
@@ -405,8 +651,12 @@ function extract(data) {
 	const textParts = [];
 	const citations = [];
 	const searchQueries = [];
+	let searchCalls = 0;
 	for (const item of data.output ?? []) {
-		if (item.type === "web_search_call" && item.action?.query) searchQueries.push(item.action.query);
+		if (item.type === "web_search_call") {
+			searchCalls += 1;
+			if (item.action?.query) searchQueries.push(item.action.query);
+		}
 		for (const content of item.content ?? []) {
 			if (content.type === "output_text" && content.text) textParts.push(content.text);
 			for (const annotation of content.annotations ?? []) if (annotation.type === "url_citation" && annotation.url) citations.push({
@@ -420,7 +670,18 @@ function extract(data) {
 	return {
 		answer: textParts.length > 0 ? textParts.join("") : data.output_text ?? "",
 		citations,
-		searchQueries
+		searchQueries,
+		searchCalls
+	};
+}
+function toUsage(params) {
+	const { usage } = params;
+	return {
+		inputTokens: usage?.input_tokens,
+		cachedInputTokens: usage?.input_tokens_details?.cached_tokens,
+		outputTokens: usage?.output_tokens,
+		totalTokens: usage?.total_tokens,
+		searchCalls: params.searchCalls
 	};
 }
 function toError(params) {
@@ -515,7 +776,7 @@ function createWebSearchTool(params = {}) {
 		name: "web_search",
 		config: {
 			title: "Web Search",
-			description: "Search the web using a provider's API key (OpenAI, Google Custom Search, or Gemini). Returns a normalized JSON result with SERP results and/or a grounded answer with citations.",
+			description: "Search the web using a provider's API key (OpenAI, Google Custom Search, or Gemini). Returns a normalized JSON result with SERP results and/or a grounded answer with citations, plus the tokens and searches used and an estimated USD cost.",
 			inputSchema: webSearchInputShape
 		},
 		handler: async (args) => {
@@ -530,6 +791,9 @@ function createWebSearchTool(params = {}) {
 					env: params.env,
 					fetchImpl: params.fetchImpl
 				});
+				try {
+					await params.onResult?.(result);
+				} catch {}
 				return { content: [{
 					type: "text",
 					text: JSON.stringify(result, null, 2)
@@ -547,4 +811,4 @@ function createWebSearchTool(params = {}) {
 	};
 }
 //#endregion
-export { coerceGeminiBackend as a, runSearch as c, formatError as d, PROVIDER_NAMES as i, WebseekError as l, webSearchInputShape as n, coerceMaxResults as o, GEMINI_BACKENDS as r, coerceProvider as s, createWebSearchTool as t, errorExitCode as u };
+export { coerceGeminiBackend as a, runSearch as c, errorExitCode as d, formatError as f, PROVIDER_NAMES as i, estimateCost as l, webSearchInputShape as n, coerceMaxResults as o, GEMINI_BACKENDS as r, coerceProvider as s, createWebSearchTool as t, WebseekError as u };