webseek 0.2.2 → 0.4.0

package/README.md

@@ -19,6 +19,38 @@ The Gemini provider supports two backends that share the same request/response
 shape: the **Gemini Developer API** (`gemini-api`, default) and **Vertex AI
 express mode** (`vertex-express`).
 
+### Usage and cost
+
+Every search reports what it consumed and an estimated cost in USD. The text
+output ends with a line such as:
+
+```
+Usage: 1,100 tokens (1,000 in, 100 out), 1 search, ~$0.0180
+```
+
+JSON output (and the MCP tool result) carries the same data as `usage` and
+`cost`, plus the `model` that served the search:
+
+```jsonc
+{
+  "model": "gpt-5.5",
+  "usage": { "inputTokens": 1000, "outputTokens": 100, "totalTokens": 1100, "searchCalls": 1 },
+  "cost": { "totalUsd": 0.018, "tokensUsd": 0.008, "searchUsd": 0.01 },
+}
+```
+
+- `usage.inputTokens` includes cached tokens (`usage.cachedInputTokens`) and the
+  search content the model read; `usage.outputTokens` includes reasoning/thinking
+  tokens. SERP providers (`google`) report no tokens.
+- `usage.searchCalls` counts OpenAI `web_search` calls, Gemini grounding queries,
+  or Google Custom Search requests (one per page of 10 results).
+- `cost` is computed from built-in list prices: token rates for the model plus
+  the provider's search fee (OpenAI $10 per 1k calls, Gemini 3.x $14 per 1k
+  queries, Gemini 2.5 $35 per 1k grounded prompts, Google Custom Search $5 per 1k
+  queries). It is a list-price estimate, not your bill: free allowances,
+  discounts and long-context rates are **not** applied. `cost` is omitted when the model has no known price
+  or the provider reported no token counts.
+
 ## Install
 
 ```bash
@@ -105,6 +137,24 @@ CommonJS consumers can `require` it the same way:
 const { runSearch } = require("webseek");
 ```
 
+Each result carries `usage` and, when it can be priced, an estimated `cost` (see
+[Usage and cost](#usage-and-cost)). To price usage yourself — for example to sum
+several searches — call `estimateCost` with the provider, the model and a
+`usage` object; it returns `undefined` when the model has no known price:
+
+```ts
+import { estimateCost } from "webseek";
+
+const cost = estimateCost({
+  provider: "openai",
+  model: "gpt-5.5",
+  usage: { inputTokens: 1000, outputTokens: 100, searchCalls: 1 },
+});
+console.log(cost?.totalUsd.toFixed(3)); // "0.018"
+```
+
+Prices are list prices built into the package and change with its releases.
+
 To embed the `web_search` tool into your own MCP server, use the
 `createWebSearchTool` factory exported from the same entry point.
 
@@ -139,6 +189,7 @@ src/
   mcp/        MCP server + the web_search tool
   lib/        runSearch — the shared core called by both CLI and MCP
   providers/  per-provider implementations (openai, google-cse, gemini)
+  pricing/    list-price table and cost estimation
   config/     credential + base-URL resolution from env
   output/     text / JSON formatting
   utils/      logger, error formatter
@@ -159,11 +210,16 @@ Publishing to npm is automated. To cut a new version:
 1. Run the `draft-release` skill — it bumps the version on a `release/vX.Y.Z`
    branch, opens a PR, and creates a **draft** GitHub release.
 2. Review and merge the release PR into `main`.
-3. Open the draft release on GitHub and click **Publish release**.
 
-Publishing the release triggers
+Merging the release PR triggers
 [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which verifies
-the tag matches `package.json` and runs `pnpm publish`. Authentication uses npm
-**trusted publishing** (OIDC) — no token secret is required, and provenance is
-generated automatically. Configure the trusted publisher for the package once on
-npmjs.com, pointing it at this repository's `publish.yml` workflow.
+the tag matches `package.json`, pushes the `vX.Y.Z` tag, runs `pnpm publish`, and
+flips the draft GitHub release public — no manual **Publish release** click is
+needed. Authentication uses npm **trusted publishing** (OIDC) — no token secret
+is required, and provenance is generated automatically. Configure the trusted
+publisher for the package once on npmjs.com, pointing it at this repository's
+`publish.yml` workflow.
+
+To run the whole flow in one shot, use the `goal-release` skill — it runs the
+`draft-release` skill, waits for the release PR's CI to pass, merges it with the
+`merge-pr` skill, and waits for the `Publish` workflow to finish.

package/dist/cli/index.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_tools = require("../tools-Ci1EDrCT.cjs");
+const require_tools = require("../tools-40nYFbvw.cjs");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let commander = require("commander");
@@ -102,7 +102,10 @@ function formatJson(result) {
 		results: result.results,
 		answer: result.answer,
 		citations: result.citations,
-		searchQueries: result.searchQueries
+		searchQueries: result.searchQueries,
+		model: result.model,
+		usage: result.usage,
+		cost: result.cost
 	};
 	if (result.raw !== void 0) payload.raw = result.raw;
 	return JSON.stringify(payload, null, 2);
@@ -128,8 +131,29 @@ function formatText(result) {
 		lines.push("");
 	}
 	if (result.searchQueries.length > 0) lines.push(`Searches: ${result.searchQueries.join(" | ")}`);
+	if (result.usage) lines.push(formatUsage({
+		usage: result.usage,
+		cost: result.cost
+	}));
 	return lines.join("\n").trimEnd();
 }
+function formatUsage(params) {
+	const { usage, cost } = params;
+	const parts = [];
+	if (usage.inputTokens !== void 0 || usage.outputTokens !== void 0) {
+		const input = usage.inputTokens ?? 0;
+		const output = usage.outputTokens ?? 0;
+		const total = usage.totalTokens ?? input + output;
+		parts.push(`${total.toLocaleString("en-US")} tokens (${input.toLocaleString("en-US")} in, ${output.toLocaleString("en-US")} out)`);
+	}
+	parts.push(`${usage.searchCalls} search${usage.searchCalls === 1 ? "" : "es"}`);
+	parts.push(cost === void 0 ? "cost unknown" : `~${formatUsd(cost.totalUsd)}`);
+	return `Usage: ${parts.join(", ")}`;
+}
+function formatUsd(value) {
+	if (value > 0 && value < 5e-5) return "<$0.0001";
+	return `$${value.toFixed(4)}`;
+}
 //#endregion
 //#region src/cli/commands/search.ts
 /**
@@ -152,10 +176,11 @@ function toSearchRequest(params) {
 	};
 }
 async function runSearchCommand(params) {
-	const result = await require_tools.runSearch(toSearchRequest({
+	const request = toSearchRequest({
 		queryParts: params.queryParts,
 		options: params.options
-	}));
+	});
+	const result = await require_tools.runSearch(request);
 	params.logger.result(formatResult({
 		result,
 		json: Boolean(params.options.json)

package/dist/cli/index.d.cts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli/index.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as coerceGeminiBackend, c as runSearch, d as formatError, l as WebseekError, o as coerceMaxResults, s as coerceProvider, t as createWebSearchTool, u as errorExitCode } from "../tools-DBF9nCIs.mjs";
+import { a as coerceGeminiBackend, c as runSearch, d as errorExitCode, f as formatError, o as coerceMaxResults, s as coerceProvider, t as createWebSearchTool, u as WebseekError } from "../tools-B4VbXLvm.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Command } from "commander";
@@ -102,7 +102,10 @@ function formatJson(result) {
 		results: result.results,
 		answer: result.answer,
 		citations: result.citations,
-		searchQueries: result.searchQueries
+		searchQueries: result.searchQueries,
+		model: result.model,
+		usage: result.usage,
+		cost: result.cost
 	};
 	if (result.raw !== void 0) payload.raw = result.raw;
 	return JSON.stringify(payload, null, 2);
@@ -128,8 +131,29 @@ function formatText(result) {
 		lines.push("");
 	}
 	if (result.searchQueries.length > 0) lines.push(`Searches: ${result.searchQueries.join(" | ")}`);
+	if (result.usage) lines.push(formatUsage({
+		usage: result.usage,
+		cost: result.cost
+	}));
 	return lines.join("\n").trimEnd();
 }
+function formatUsage(params) {
+	const { usage, cost } = params;
+	const parts = [];
+	if (usage.inputTokens !== void 0 || usage.outputTokens !== void 0) {
+		const input = usage.inputTokens ?? 0;
+		const output = usage.outputTokens ?? 0;
+		const total = usage.totalTokens ?? input + output;
+		parts.push(`${total.toLocaleString("en-US")} tokens (${input.toLocaleString("en-US")} in, ${output.toLocaleString("en-US")} out)`);
+	}
+	parts.push(`${usage.searchCalls} search${usage.searchCalls === 1 ? "" : "es"}`);
+	parts.push(cost === void 0 ? "cost unknown" : `~${formatUsd(cost.totalUsd)}`);
+	return `Usage: ${parts.join(", ")}`;
+}
+function formatUsd(value) {
+	if (value > 0 && value < 5e-5) return "<$0.0001";
+	return `$${value.toFixed(4)}`;
+}
 //#endregion
 //#region src/cli/commands/search.ts
 /**
@@ -152,10 +176,11 @@ function toSearchRequest(params) {
 	};
 }
 async function runSearchCommand(params) {
-	const result = await runSearch(toSearchRequest({
+	const request = toSearchRequest({
 		queryParts: params.queryParts,
 		options: params.options
-	}));
+	});
+	const result = await runSearch(request);
 	params.logger.result(formatResult({
 		result,
 		json: Boolean(params.options.json)

package/dist/index.cjs

@@ -1,10 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_tools = require("./tools-Ci1EDrCT.cjs");
+const require_tools = require("./tools-40nYFbvw.cjs");
 exports.GEMINI_BACKENDS = require_tools.GEMINI_BACKENDS;
 exports.PROVIDER_NAMES = require_tools.PROVIDER_NAMES;
 exports.WebseekError = require_tools.WebseekError;
 exports.createWebSearchTool = require_tools.createWebSearchTool;
 exports.errorExitCode = require_tools.errorExitCode;
+exports.estimateCost = require_tools.estimateCost;
 exports.formatError = require_tools.formatError;
 exports.runSearch = require_tools.runSearch;
 exports.webSearchInputShape = require_tools.webSearchInputShape;

package/dist/index.d.cts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-
 //#region src/config/env.d.ts
 /**
  * Resolves provider credentials and configuration from environment variables.
@@ -42,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;
@@ -54,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;
 }
@@ -76,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;
@@ -88,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
 /**
@@ -105,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);
 }
@@ -113,17 +157,17 @@ 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<{
-    openai: "openai";
-    google: "google";
     gemini: "gemini";
+    google: "google";
+    openai: "openai";
   }>;
   maxResults: z.ZodOptional<z.ZodNumber>;
   model: z.ZodOptional<z.ZodString>;
@@ -136,9 +180,9 @@ declare const webSearchInputShape: {
 declare const webSearchArgsSchema: z.ZodObject<{
   query: z.ZodString;
   provider: z.ZodEnum<{
-    openai: "openai";
-    google: "google";
     gemini: "gemini";
+    google: "google";
+    openai: "openai";
   }>;
   maxResults: z.ZodOptional<z.ZodNumber>;
   model: z.ZodOptional<z.ZodString>;
@@ -172,6 +216,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.d.mts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-
 //#region src/config/env.d.ts
 /**
  * Resolves provider credentials and configuration from environment variables.
@@ -42,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;
@@ -54,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;
 }
@@ -76,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;
@@ -88,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
 /**
@@ -105,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);
 }
@@ -113,17 +157,17 @@ 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<{
-    openai: "openai";
-    google: "google";
     gemini: "gemini";
+    google: "google";
+    openai: "openai";
   }>;
   maxResults: z.ZodOptional<z.ZodNumber>;
   model: z.ZodOptional<z.ZodString>;
@@ -136,9 +180,9 @@ declare const webSearchInputShape: {
 declare const webSearchArgsSchema: z.ZodObject<{
   query: z.ZodString;
   provider: z.ZodEnum<{
-    openai: "openai";
-    google: "google";
     gemini: "gemini";
+    google: "google";
+    openai: "openai";
   }>;
   maxResults: z.ZodOptional<z.ZodNumber>;
   model: z.ZodOptional<z.ZodString>;
@@ -172,6 +216,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-B4VbXLvm.mjs";
+export { GEMINI_BACKENDS, PROVIDER_NAMES, WebseekError, createWebSearchTool, errorExitCode, estimateCost, formatError, runSearch, webSearchInputShape };

package/dist/{tools-Ci1EDrCT.cjs → tools-40nYFbvw.cjs}

@@ -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 = zod.z.looseObject({
 	content: zod.z.looseObject({ parts: zod.z.array(zod.z.looseObject({ text: zod.z.string().optional() })).optional() }).optional(),
 	groundingMetadata: groundingMetadataSchema.optional()
 });
+const usageMetadataSchema = zod.z.looseObject({
+	promptTokenCount: zod.z.number().optional(),
+	cachedContentTokenCount: zod.z.number().optional(),
+	candidatesTokenCount: zod.z.number().optional(),
+	thoughtsTokenCount: zod.z.number().optional(),
+	toolUsePromptTokenCount: zod.z.number().optional(),
+	totalTokenCount: zod.z.number().optional()
+});
 const responseSchema$2 = zod.z.looseObject({
 	candidates: zod.z.array(candidateSchema).optional(),
+	usageMetadata: usageMetadataSchema.optional(),
+	modelVersion: zod.z.string().optional(),
 	error: zod.z.looseObject({ message: zod.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 = zod.z.looseObject({
 	content: zod.z.array(contentSchema).optional(),
 	action: zod.z.looseObject({ query: zod.z.string().optional() }).optional()
 });
+const usageSchema = zod.z.looseObject({
+	input_tokens: zod.z.number().optional(),
+	input_tokens_details: zod.z.looseObject({ cached_tokens: zod.z.number().optional() }).nullish(),
+	output_tokens: zod.z.number().optional(),
+	total_tokens: zod.z.number().optional()
+});
 const responseSchema = zod.z.looseObject({
 	output: zod.z.array(outputItemSchema).optional(),
 	output_text: zod.z.string().optional(),
+	model: zod.z.string().optional(),
+	usage: usageSchema.nullish(),
 	error: zod.z.looseObject({ message: zod.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) => {
@@ -595,6 +856,12 @@ Object.defineProperty(exports, "errorExitCode", {
 		return errorExitCode;
 	}
 });
+Object.defineProperty(exports, "estimateCost", {
+	enumerable: true,
+	get: function() {
+		return estimateCost;
+	}
+});
 Object.defineProperty(exports, "formatError", {
 	enumerable: true,
 	get: function() {

package/dist/{tools-DBF9nCIs.mjs → tools-B4VbXLvm.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) => {
@@ -547,4 +808,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webseek",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Unified multi-provider web search as a CLI, MCP server, and library (OpenAI, Google Custom Search, Gemini)",
   "keywords": [
     "web-search",
@@ -54,23 +54,24 @@
     "access": "public"
   },
   "devDependencies": {
-    "@openrouter/sdk": "0.13.7",
-    "@secretlint/secretlint-rule-preset-recommend": "13.0.2",
+    "@openrouter/sdk": "1.3.21",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^26.0.0",
-    "cspell": "10.0.1",
-    "lint-staged": "17.0.7",
-    "oxfmt": "0.55.0",
-    "oxlint": "1.70.0",
-    "repomix": "1.14.1",
-    "resend": "6.14.0",
-    "rulesync": "^8.31.0",
-    "secretlint": "13.0.2",
-    "simple-git-hooks": "2.13.1",
-    "tsdown": "^0.22.3",
+    "cspell": "10.3.3",
+    "lint-staged": "17.5.1",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
+    "repomix": "1.18.1",
+    "resend": "6.28.1",
+    "rulesync": "^17.0.0",
+    "secretlint": "13.0.5",
+    "simple-git-hooks": "2.14.0",
+    "smol-toml": "1.9.0",
+    "tsdown": "^0.23.0",
     "tsx": "^4.22.4",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -94,8 +95,9 @@
     "test:e2e": "vitest run --config vitest.e2e.config.ts --silent=false",
     "sync:skill-docs": "tsx scripts/sync-skill-docs.ts",
     "check:sync-skill-docs": "tsx scripts/check-skill-docs-sync.ts",
+    "check:codex-config": "tsx scripts/check-codex-config.ts",
     "cicheck:code": "pnpm run check && pnpm run test",
-    "cicheck:content": "pnpm run check:sync-skill-docs && pnpm run cspell && pnpm run secretlint",
+    "cicheck:content": "pnpm run check:sync-skill-docs && pnpm run check:codex-config && pnpm run cspell && pnpm run secretlint",
     "cicheck": "pnpm run cicheck:code && pnpm run cicheck:content",
     "generate": "rulesync generate",
     "gitignore": "rulesync gitignore"