webseek 0.4.0 → 0.5.0

package/README.md

@@ -51,6 +51,9 @@ JSON output (and the MCP tool result) carries the same data as `usage` and
   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.
 
+The CLI and the MCP server also append every successful search to a local usage
+log, which [`webseek stats`](#usage-stats) totals.
+
 ## Install
 
 ```bash
@@ -93,6 +96,54 @@ webseek "summarize the latest TypeScript release" -p openai
 webseek "who won euro 2024" -p gemini --gemini-backend vertex-express --json
 ```
 
+`mcp` and `stats` are subcommands: a query whose first word is `mcp` or
+`stats` must be quoted as a whole (`webseek "stats for the nba" -p openai`), and
+a query of just that one word cannot be searched from the CLI.
+
+### Usage stats
+
+Every successful search — from the CLI or the MCP server — is appended as one
+JSON line to `usage.jsonl` in the data directory: the time, provider, model,
+`usage` and `cost`. The query text is **not** stored. `webseek stats` totals
+the log, with flags modelled on `opencode stats`:
+
+```bash
+webseek stats                  # this year so far
+webseek stats --days 7 --full  # the last 7 days with every section
+webseek stats --all -p openai --models
+```
+
+```
+webseek stats · 2026 so far · all providers
+
+3 searches · 4 search calls · 12.9k tokens
+~$0.0550 estimated · 1 active day
+```
+
+| Flag                    | Description                                         |
+| ----------------------- | --------------------------------------------------- |
+| `--days <n>`            | The last N days; `0` means today                    |
+| `--year <year>`         | A calendar year (default: this year so far)         |
+| `--all`                 | Lifetime statistics                                 |
+| `-p, --provider <name>` | Only count one provider                             |
+| `--cost`                | Cost split (tokens / search fees) and token details |
+| `--models`              | Searches, tokens and cost per model                 |
+| `--full`                | Every detailed section                              |
+| `--limit <n>`           | Number of rows in the models section                |
+| `--json`                | Statistics as JSON                                  |
+
+`--days`, `--year` and `--all` cannot be combined. Costs are the same list-price
+estimates as in each search's output; searches whose model has no known price
+are counted but left out of the cost (and reported as unpriced).
+
+| Environment variable | Effect                                                                           |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `WEBSEEK_DATA_DIR`   | Data directory (default `$XDG_DATA_HOME/webseek`, else `~/.local/share/webseek`) |
+| `WEBSEEK_USAGE_LOG`  | Set to `0`, `false` or `off` to stop recording searches                          |
+
+Delete `usage.jsonl` to reset the statistics. A failure to write the log is
+reported as a warning on stderr and never fails the search.
+
 ## MCP server mode
 
 Start a [Model Context Protocol](https://modelcontextprotocol.io) server over
@@ -156,7 +207,11 @@ 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.
+`createWebSearchTool` factory exported from the same entry point. Its optional
+`onResult` callback receives every successful result (the `webseek mcp` server
+uses it to write the usage log).
+
+The library itself never writes the usage log; only the CLI and `webseek mcp` do.
 
 ## Authentication
 
@@ -185,11 +240,12 @@ they don't leak into shell history or process listings.
 ```
 src/
   index.ts    public library entry (runSearch, types, createWebSearchTool)
-  cli/        commander program: root search command and `mcp` command
+  cli/        commander program: root search command, `mcp` and `stats` commands
   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
+  stats/      local usage log, aggregation and the `stats` report
   config/     credential + base-URL resolution from env
   output/     text / JSON formatting
   utils/      logger, error formatter

package/dist/cli/index.cjs

@@ -1,10 +1,122 @@
 #!/usr/bin/env node
-const require_tools = require("../tools-40nYFbvw.cjs");
+const require_tools = require("../tools-Brr43TiA.cjs");
+let zod = require("zod");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let commander = require("commander");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
+//#region src/stats/usage-log.ts
+/**
+* The local usage log: one JSON line per successful search, appended by the
+* CLI and the MCP server and read back by `webseek stats`.
+*
+* Records hold what a search consumed and cost — never the query text — so the
+* log is safe to keep around. The library entry point never writes to it.
+*/
+const USAGE_LOG_FILE = "usage.jsonl";
+const RECORD_VERSION = 1;
+/**
+* The directory the usage log lives in: `WEBSEEK_DATA_DIR`, else
+* `$XDG_DATA_HOME/webseek`, else `~/.local/share/webseek`.
+*/
+function resolveDataDir(params = {}) {
+	const env = params.env ?? process.env;
+	if (env.WEBSEEK_DATA_DIR) return env.WEBSEEK_DATA_DIR;
+	if (env.XDG_DATA_HOME) return (0, node_path.join)(env.XDG_DATA_HOME, "webseek");
+	return (0, node_path.join)((0, node_os.homedir)(), ".local", "share", "webseek");
+}
+function resolveUsageLogPath(params = {}) {
+	return (0, node_path.join)(resolveDataDir(params), USAGE_LOG_FILE);
+}
+/** Logging is on unless `WEBSEEK_USAGE_LOG` is `0`, `false` or `off`. */
+function isUsageLogEnabled(params = {}) {
+	const value = (params.env ?? process.env).WEBSEEK_USAGE_LOG?.trim().toLowerCase();
+	return value !== "0" && value !== "false" && value !== "off";
+}
+function toUsageRecord(params) {
+	const { result } = params;
+	return {
+		v: RECORD_VERSION,
+		at: params.now ?? Date.now(),
+		provider: result.provider,
+		model: result.model,
+		usage: result.usage,
+		cost: result.cost
+	};
+}
+/**
+* Append a search to the usage log. Never throws: a failed write is reported
+* through `onError` so it cannot fail (or corrupt the output of) the search.
+*/
+async function appendUsageRecord(params) {
+	if (!isUsageLogEnabled({ env: params.env })) return;
+	try {
+		const dir = resolveDataDir({ env: params.env });
+		await (0, node_fs_promises.mkdir)(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const record = toUsageRecord({
+			result: params.result,
+			now: params.now
+		});
+		await (0, node_fs_promises.appendFile)((0, node_path.join)(dir, USAGE_LOG_FILE), `${JSON.stringify(record)}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	} catch (error) {
+		params.onError?.(error);
+	}
+}
+/** Read every valid record from the usage log; a missing log reads as empty. */
+async function readUsageRecords(params = {}) {
+	let text;
+	try {
+		text = await (0, node_fs_promises.readFile)(resolveUsageLogPath(params), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	return parseUsageRecords(text);
+}
+const usageRecordSchema = zod.z.looseObject({
+	v: zod.z.literal(RECORD_VERSION),
+	at: zod.z.number(),
+	provider: zod.z.enum(require_tools.PROVIDER_NAMES),
+	model: zod.z.string().optional(),
+	usage: zod.z.looseObject({
+		inputTokens: zod.z.number().optional(),
+		cachedInputTokens: zod.z.number().optional(),
+		outputTokens: zod.z.number().optional(),
+		totalTokens: zod.z.number().optional(),
+		searchCalls: zod.z.number()
+	}).optional(),
+	cost: zod.z.looseObject({
+		totalUsd: zod.z.number(),
+		tokensUsd: zod.z.number(),
+		searchUsd: zod.z.number()
+	}).optional()
+});
+/** Parse JSONL, skipping blank, malformed and unknown-version lines. */
+function parseUsageRecords(text) {
+	const records = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		let json;
+		try {
+			json = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const parsed = usageRecordSchema.safeParse(json);
+		if (parsed.success) records.push(parsed.data);
+	}
+	return records;
+}
+//#endregion
 //#region src/mcp/server.ts
 /**
 * MCP server mode: exposes the `web_search` tool over the stdio transport so
@@ -17,7 +129,10 @@ async function startMcpServer(params) {
 		name: "webseek",
 		version: params.version
 	});
-	const tool = require_tools.createWebSearchTool();
+	const tool = require_tools.createWebSearchTool({ onResult: (result) => appendUsageRecord({
+		result,
+		onError: (error) => params.logger.warn(`could not record usage: ${require_tools.formatError(error)}`)
+	}) });
 	server.registerTool(tool.name, tool.config, tool.handler);
 	const transport = new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport();
 	await server.connect(transport);
@@ -181,6 +296,10 @@ async function runSearchCommand(params) {
 		options: params.options
 	});
 	const result = await require_tools.runSearch(request);
+	await appendUsageRecord({
+		result,
+		onError: (error) => params.logger.warn(`could not record usage: ${require_tools.formatError(error)}`)
+	});
 	params.logger.result(formatResult({
 		result,
 		json: Boolean(params.options.json)
@@ -200,6 +319,293 @@ function registerSearchCommand(program) {
 	}));
 }
 //#endregion
+//#region src/stats/aggregate.ts
+/**
+* `--all` → all time; `--days N` → since local midnight N-1 days ago (0 or 1
+* mean today); `--year Y` → that calendar year; default → this year so far.
+*/
+function resolveStatsRange(params = {}) {
+	const now = params.now ?? /* @__PURE__ */ new Date();
+	const to = now.getTime() + 1;
+	if (params.all) return {
+		from: void 0,
+		to,
+		label: "all time"
+	};
+	if (params.days !== void 0) {
+		const from = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+		from.setDate(from.getDate() - Math.max(0, params.days - 1));
+		return {
+			from: from.getTime(),
+			to,
+			label: params.days <= 1 ? "today" : `last ${params.days} days`
+		};
+	}
+	const year = params.year ?? now.getFullYear();
+	const isCurrentYear = year === now.getFullYear();
+	return {
+		from: new Date(year, 0, 1).getTime(),
+		to: isCurrentYear ? to : new Date(year + 1, 0, 1).getTime(),
+		label: isCurrentYear ? `${year} so far` : String(year)
+	};
+}
+function aggregateUsage(params) {
+	const { range } = params;
+	const stats = {
+		range: {
+			from: range.from,
+			to: range.to
+		},
+		searches: 0,
+		searchCalls: 0,
+		tokens: {
+			input: 0,
+			cachedInput: 0,
+			output: 0,
+			total: 0
+		},
+		cost: {
+			totalUsd: 0,
+			tokensUsd: 0,
+			searchUsd: 0
+		},
+		unpricedSearches: 0,
+		activeDays: 0,
+		models: []
+	};
+	const days = /* @__PURE__ */ new Set();
+	const models = /* @__PURE__ */ new Map();
+	for (const record of params.records) {
+		if (!((range.from === void 0 || record.at >= range.from) && record.at < range.to) || params.provider !== void 0 && record.provider !== params.provider) continue;
+		addRecord({
+			stats,
+			models,
+			record
+		});
+		const at = new Date(record.at);
+		days.add(`${at.getFullYear()}-${at.getMonth()}-${at.getDate()}`);
+	}
+	stats.activeDays = days.size;
+	stats.models = [...models.values()].toSorted((a, b) => b.costUsd - a.costUsd || b.searches - a.searches);
+	return stats;
+}
+function addRecord(params) {
+	const { stats, record } = params;
+	const usage = record.usage;
+	const input = usage?.inputTokens ?? 0;
+	const output = usage?.outputTokens ?? 0;
+	const total = usage?.totalTokens ?? input + output;
+	const searchCalls = usage?.searchCalls ?? 0;
+	stats.searches += 1;
+	stats.searchCalls += searchCalls;
+	stats.tokens.input += input;
+	stats.tokens.cachedInput += usage?.cachedInputTokens ?? 0;
+	stats.tokens.output += output;
+	stats.tokens.total += total;
+	if (record.cost) {
+		stats.cost.totalUsd += record.cost.totalUsd;
+		stats.cost.tokensUsd += record.cost.tokensUsd;
+		stats.cost.searchUsd += record.cost.searchUsd;
+	} else stats.unpricedSearches += 1;
+	const key = `${record.provider}/${record.model ?? ""}`;
+	const model = params.models.get(key) ?? {
+		provider: record.provider,
+		model: record.model,
+		searches: 0,
+		searchCalls: 0,
+		tokens: 0,
+		costUsd: 0,
+		unpricedSearches: 0
+	};
+	model.searches += 1;
+	model.searchCalls += searchCalls;
+	model.tokens += total;
+	model.costUsd += record.cost?.totalUsd ?? 0;
+	if (!record.cost) model.unpricedSearches += 1;
+	params.models.set(key, model);
+}
+//#endregion
+//#region src/stats/render.ts
+/**
+* Renders aggregated usage as the `webseek stats` text report, laid out after
+* `opencode stats`: a summary by default, plus COST & TOKENS and MODELS
+* sections on request.
+*/
+function renderStats(params) {
+	const { stats } = params;
+	const detailed = params.cost || params.models;
+	const header = `webseek stats · ${params.label} · ${params.scope}`;
+	const lines = [];
+	if (detailed) lines.push(`${params.label} · ${params.scope}`);
+	else if (stats.searches === 0) lines.push(header, "", "no searches in this range");
+	else {
+		lines.push(header, "", `${plural({
+			value: stats.searches,
+			singular: "search",
+			pluralForm: "searches"
+		})} · ${plural({
+			value: stats.searchCalls,
+			singular: "search call"
+		})} · ${plural({
+			value: stats.tokens.total,
+			singular: "token"
+		})}`, `~${formatUsd(stats.cost.totalUsd)} estimated · ${plural({
+			value: stats.activeDays,
+			singular: "active day"
+		})}`);
+		if (stats.unpricedSearches > 0) lines.push(`${plural({
+			value: stats.unpricedSearches,
+			singular: "search",
+			pluralForm: "searches"
+		})} without a price estimate`);
+	}
+	if (params.cost) lines.push("", ...renderCost(stats));
+	if (params.models) lines.push("", ...renderModels({
+		models: stats.models,
+		limit: params.limit
+	}));
+	return lines.join("\n");
+}
+function renderCost(stats) {
+	const rows = [
+		["cost", `~${formatUsd(stats.cost.totalUsd)}`],
+		["  tokens", formatUsd(stats.cost.tokensUsd)],
+		["  search fees", formatUsd(stats.cost.searchUsd)],
+		["input", compact(stats.tokens.input)],
+		["cached input", compact(stats.tokens.cachedInput)],
+		["output", compact(stats.tokens.output)],
+		["search calls", compact(stats.searchCalls)]
+	];
+	if (stats.unpricedSearches > 0) rows.push(["unpriced searches", compact(stats.unpricedSearches)]);
+	return ["COST & TOKENS", ...rows.map(([label, value]) => `  ${label.padEnd(20)}${value}`)];
+}
+function renderModels(params) {
+	const { models, limit } = params;
+	if (models.length === 0) return ["MODELS", "  no searches"];
+	const shown = limit === void 0 ? models : models.slice(0, limit);
+	const rest = models.length - shown.length;
+	return [
+		"MODELS",
+		tableRow({
+			name: "model",
+			searches: "searches",
+			tokens: "tokens",
+			cost: "cost"
+		}),
+		...shown.map((model) => tableRow({
+			name: modelName(model),
+			searches: compact(model.searches),
+			tokens: compact(model.tokens),
+			cost: model.unpricedSearches === model.searches ? "-" : formatUsd(model.costUsd)
+		})),
+		...rest > 0 ? ["", `+${rest.toLocaleString("en-US")} more model${rest === 1 ? "" : "s"}`] : []
+	];
+}
+function modelName(model) {
+	const name = model.model?.replace(/\p{Cc}/gu, "");
+	return name ? `${model.provider}/${name}` : model.provider;
+}
+function tableRow(cells) {
+	return `${(cells.name.length <= 34 ? cells.name : `${cells.name.slice(0, 33)}…`).padEnd(34)}${cells.searches.padStart(10)}${cells.tokens.padStart(10)}${cells.cost.padStart(12)}`;
+}
+/** 1234 → "1.2k", 2_000_000 → "2m". */
+function compact(value) {
+	if (value >= 1e9) return `${oneDecimal(value / 1e9)}b`;
+	if (value >= 1e6) return `${oneDecimal(value / 1e6)}m`;
+	if (value >= 1e3) return `${oneDecimal(value / 1e3)}k`;
+	return Math.round(value).toLocaleString("en-US");
+}
+function oneDecimal(value) {
+	return value.toFixed(1).replace(/\.0$/, "");
+}
+function plural(params) {
+	const noun = params.value === 1 ? params.singular : params.pluralForm ?? `${params.singular}s`;
+	return `${compact(params.value)} ${noun}`;
+}
+//#endregion
+//#region src/cli/commands/stats.ts
+/** Validate CLI options into a stats request. Pure apart from reading `now`. */
+function toStatsRequest(params) {
+	const { options } = params;
+	if ([
+		options.days !== void 0,
+		options.year !== void 0,
+		options.all
+	].filter(Boolean).length > 1) throw new require_tools.WebseekError({
+		code: "invalid_usage",
+		message: "--days, --year, and --all cannot be combined."
+	});
+	return {
+		range: resolveStatsRange({
+			days: options.days === void 0 ? void 0 : parseInteger({
+				name: "days",
+				value: options.days,
+				min: 0,
+				max: 36500
+			}),
+			year: options.year === void 0 ? void 0 : parseInteger({
+				name: "year",
+				value: options.year,
+				min: 1970,
+				max: 9999
+			}),
+			all: options.all,
+			now: params.now
+		}),
+		provider: options.provider === void 0 ? void 0 : require_tools.coerceProvider(options.provider),
+		cost: Boolean(options.cost || options.full),
+		models: Boolean(options.models || options.full),
+		limit: options.limit === void 0 ? void 0 : parseInteger({
+			name: "limit",
+			value: options.limit,
+			min: 1,
+			max: Number.MAX_SAFE_INTEGER
+		}),
+		json: Boolean(options.json)
+	};
+}
+function parseInteger(params) {
+	const { name, value, min, max } = params;
+	const parsed = Number(value);
+	if (!/^\d+$/.test(value.trim()) || !Number.isSafeInteger(parsed) || parsed < min || parsed > max) throw new require_tools.WebseekError({
+		code: "invalid_usage",
+		message: `--${name} must be an integer between ${min} and ${max}.`
+	});
+	return parsed;
+}
+async function runStatsCommand(params) {
+	const request = toStatsRequest({ options: params.options });
+	const stats = aggregateUsage({
+		records: await readUsageRecords({ env: params.env }),
+		range: request.range,
+		provider: request.provider
+	});
+	if (request.json) {
+		const models = request.limit === void 0 ? stats.models : stats.models.slice(0, request.limit);
+		params.logger.result(JSON.stringify({
+			...stats,
+			models
+		}, null, 2));
+		return;
+	}
+	params.logger.result(renderStats({
+		stats,
+		label: request.range.label,
+		scope: request.provider ?? "all providers",
+		cost: request.cost,
+		models: request.models,
+		limit: request.limit
+	}));
+}
+function registerStatsCommand(program) {
+	program.command("stats").description("Show usage and estimated cost of the searches recorded locally").option("--days <n>", "show the last N days; 0 means today").option("--year <year>", "show a calendar year").option("--all", "show lifetime statistics").option("-p, --provider <name>", "only count one provider: openai | google | gemini").option("--cost", "show cost and token details").option("--models", "show usage per model").option("--full", "show every detailed section").option("--limit <n>", "number of rows in the models section").option("--json", "output statistics as JSON").action(wrapCommand(async ({ logger }, options) => {
+		await runStatsCommand({
+			logger,
+			options
+		});
+	}));
+}
+//#endregion
 //#region src/cli/index.ts
 /**
 * webseek CLI entry point.
@@ -207,6 +613,7 @@ function registerSearchCommand(program) {
 * Two modes:
 *   webseek <query> --provider <name>   run a one-off web search (root command)
 *   webseek mcp                         start the MCP server (stdio)
+*   webseek stats                       summarize the locally recorded usage
 */
 function readPackageVersion(dir) {
 	try {
@@ -228,12 +635,13 @@ function getVersion() {
 function buildProgram() {
 	const program = new commander.Command();
 	const version = getVersion();
-	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version");
+	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version").enablePositionalOptions();
 	registerSearchCommand(program);
 	registerMcpCommand({
 		program,
 		version
 	});
+	registerStatsCommand(program);
 	return program;
 }
 async function main() {

package/dist/cli/index.mjs

@@ -1,10 +1,122 @@
 #!/usr/bin/env node
-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 { a as coerceGeminiBackend, c as runSearch, d as errorExitCode, f as formatError, i as PROVIDER_NAMES, o as coerceMaxResults, s as coerceProvider, t as createWebSearchTool, u as WebseekError } from "../tools-1ZllUYBx.mjs";
+import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Command } from "commander";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+//#region src/stats/usage-log.ts
+/**
+* The local usage log: one JSON line per successful search, appended by the
+* CLI and the MCP server and read back by `webseek stats`.
+*
+* Records hold what a search consumed and cost — never the query text — so the
+* log is safe to keep around. The library entry point never writes to it.
+*/
+const USAGE_LOG_FILE = "usage.jsonl";
+const RECORD_VERSION = 1;
+/**
+* The directory the usage log lives in: `WEBSEEK_DATA_DIR`, else
+* `$XDG_DATA_HOME/webseek`, else `~/.local/share/webseek`.
+*/
+function resolveDataDir(params = {}) {
+	const env = params.env ?? process.env;
+	if (env.WEBSEEK_DATA_DIR) return env.WEBSEEK_DATA_DIR;
+	if (env.XDG_DATA_HOME) return join(env.XDG_DATA_HOME, "webseek");
+	return join(homedir(), ".local", "share", "webseek");
+}
+function resolveUsageLogPath(params = {}) {
+	return join(resolveDataDir(params), USAGE_LOG_FILE);
+}
+/** Logging is on unless `WEBSEEK_USAGE_LOG` is `0`, `false` or `off`. */
+function isUsageLogEnabled(params = {}) {
+	const value = (params.env ?? process.env).WEBSEEK_USAGE_LOG?.trim().toLowerCase();
+	return value !== "0" && value !== "false" && value !== "off";
+}
+function toUsageRecord(params) {
+	const { result } = params;
+	return {
+		v: RECORD_VERSION,
+		at: params.now ?? Date.now(),
+		provider: result.provider,
+		model: result.model,
+		usage: result.usage,
+		cost: result.cost
+	};
+}
+/**
+* Append a search to the usage log. Never throws: a failed write is reported
+* through `onError` so it cannot fail (or corrupt the output of) the search.
+*/
+async function appendUsageRecord(params) {
+	if (!isUsageLogEnabled({ env: params.env })) return;
+	try {
+		const dir = resolveDataDir({ env: params.env });
+		await mkdir(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const record = toUsageRecord({
+			result: params.result,
+			now: params.now
+		});
+		await appendFile(join(dir, USAGE_LOG_FILE), `${JSON.stringify(record)}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	} catch (error) {
+		params.onError?.(error);
+	}
+}
+/** Read every valid record from the usage log; a missing log reads as empty. */
+async function readUsageRecords(params = {}) {
+	let text;
+	try {
+		text = await readFile(resolveUsageLogPath(params), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	return parseUsageRecords(text);
+}
+const usageRecordSchema = z.looseObject({
+	v: z.literal(RECORD_VERSION),
+	at: z.number(),
+	provider: z.enum(PROVIDER_NAMES),
+	model: z.string().optional(),
+	usage: z.looseObject({
+		inputTokens: z.number().optional(),
+		cachedInputTokens: z.number().optional(),
+		outputTokens: z.number().optional(),
+		totalTokens: z.number().optional(),
+		searchCalls: z.number()
+	}).optional(),
+	cost: z.looseObject({
+		totalUsd: z.number(),
+		tokensUsd: z.number(),
+		searchUsd: z.number()
+	}).optional()
+});
+/** Parse JSONL, skipping blank, malformed and unknown-version lines. */
+function parseUsageRecords(text) {
+	const records = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		let json;
+		try {
+			json = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const parsed = usageRecordSchema.safeParse(json);
+		if (parsed.success) records.push(parsed.data);
+	}
+	return records;
+}
+//#endregion
 //#region src/mcp/server.ts
 /**
 * MCP server mode: exposes the `web_search` tool over the stdio transport so
@@ -17,7 +129,10 @@ async function startMcpServer(params) {
 		name: "webseek",
 		version: params.version
 	});
-	const tool = createWebSearchTool();
+	const tool = createWebSearchTool({ onResult: (result) => appendUsageRecord({
+		result,
+		onError: (error) => params.logger.warn(`could not record usage: ${formatError(error)}`)
+	}) });
 	server.registerTool(tool.name, tool.config, tool.handler);
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
@@ -181,6 +296,10 @@ async function runSearchCommand(params) {
 		options: params.options
 	});
 	const result = await runSearch(request);
+	await appendUsageRecord({
+		result,
+		onError: (error) => params.logger.warn(`could not record usage: ${formatError(error)}`)
+	});
 	params.logger.result(formatResult({
 		result,
 		json: Boolean(params.options.json)
@@ -200,6 +319,293 @@ function registerSearchCommand(program) {
 	}));
 }
 //#endregion
+//#region src/stats/aggregate.ts
+/**
+* `--all` → all time; `--days N` → since local midnight N-1 days ago (0 or 1
+* mean today); `--year Y` → that calendar year; default → this year so far.
+*/
+function resolveStatsRange(params = {}) {
+	const now = params.now ?? /* @__PURE__ */ new Date();
+	const to = now.getTime() + 1;
+	if (params.all) return {
+		from: void 0,
+		to,
+		label: "all time"
+	};
+	if (params.days !== void 0) {
+		const from = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+		from.setDate(from.getDate() - Math.max(0, params.days - 1));
+		return {
+			from: from.getTime(),
+			to,
+			label: params.days <= 1 ? "today" : `last ${params.days} days`
+		};
+	}
+	const year = params.year ?? now.getFullYear();
+	const isCurrentYear = year === now.getFullYear();
+	return {
+		from: new Date(year, 0, 1).getTime(),
+		to: isCurrentYear ? to : new Date(year + 1, 0, 1).getTime(),
+		label: isCurrentYear ? `${year} so far` : String(year)
+	};
+}
+function aggregateUsage(params) {
+	const { range } = params;
+	const stats = {
+		range: {
+			from: range.from,
+			to: range.to
+		},
+		searches: 0,
+		searchCalls: 0,
+		tokens: {
+			input: 0,
+			cachedInput: 0,
+			output: 0,
+			total: 0
+		},
+		cost: {
+			totalUsd: 0,
+			tokensUsd: 0,
+			searchUsd: 0
+		},
+		unpricedSearches: 0,
+		activeDays: 0,
+		models: []
+	};
+	const days = /* @__PURE__ */ new Set();
+	const models = /* @__PURE__ */ new Map();
+	for (const record of params.records) {
+		if (!((range.from === void 0 || record.at >= range.from) && record.at < range.to) || params.provider !== void 0 && record.provider !== params.provider) continue;
+		addRecord({
+			stats,
+			models,
+			record
+		});
+		const at = new Date(record.at);
+		days.add(`${at.getFullYear()}-${at.getMonth()}-${at.getDate()}`);
+	}
+	stats.activeDays = days.size;
+	stats.models = [...models.values()].toSorted((a, b) => b.costUsd - a.costUsd || b.searches - a.searches);
+	return stats;
+}
+function addRecord(params) {
+	const { stats, record } = params;
+	const usage = record.usage;
+	const input = usage?.inputTokens ?? 0;
+	const output = usage?.outputTokens ?? 0;
+	const total = usage?.totalTokens ?? input + output;
+	const searchCalls = usage?.searchCalls ?? 0;
+	stats.searches += 1;
+	stats.searchCalls += searchCalls;
+	stats.tokens.input += input;
+	stats.tokens.cachedInput += usage?.cachedInputTokens ?? 0;
+	stats.tokens.output += output;
+	stats.tokens.total += total;
+	if (record.cost) {
+		stats.cost.totalUsd += record.cost.totalUsd;
+		stats.cost.tokensUsd += record.cost.tokensUsd;
+		stats.cost.searchUsd += record.cost.searchUsd;
+	} else stats.unpricedSearches += 1;
+	const key = `${record.provider}/${record.model ?? ""}`;
+	const model = params.models.get(key) ?? {
+		provider: record.provider,
+		model: record.model,
+		searches: 0,
+		searchCalls: 0,
+		tokens: 0,
+		costUsd: 0,
+		unpricedSearches: 0
+	};
+	model.searches += 1;
+	model.searchCalls += searchCalls;
+	model.tokens += total;
+	model.costUsd += record.cost?.totalUsd ?? 0;
+	if (!record.cost) model.unpricedSearches += 1;
+	params.models.set(key, model);
+}
+//#endregion
+//#region src/stats/render.ts
+/**
+* Renders aggregated usage as the `webseek stats` text report, laid out after
+* `opencode stats`: a summary by default, plus COST & TOKENS and MODELS
+* sections on request.
+*/
+function renderStats(params) {
+	const { stats } = params;
+	const detailed = params.cost || params.models;
+	const header = `webseek stats · ${params.label} · ${params.scope}`;
+	const lines = [];
+	if (detailed) lines.push(`${params.label} · ${params.scope}`);
+	else if (stats.searches === 0) lines.push(header, "", "no searches in this range");
+	else {
+		lines.push(header, "", `${plural({
+			value: stats.searches,
+			singular: "search",
+			pluralForm: "searches"
+		})} · ${plural({
+			value: stats.searchCalls,
+			singular: "search call"
+		})} · ${plural({
+			value: stats.tokens.total,
+			singular: "token"
+		})}`, `~${formatUsd(stats.cost.totalUsd)} estimated · ${plural({
+			value: stats.activeDays,
+			singular: "active day"
+		})}`);
+		if (stats.unpricedSearches > 0) lines.push(`${plural({
+			value: stats.unpricedSearches,
+			singular: "search",
+			pluralForm: "searches"
+		})} without a price estimate`);
+	}
+	if (params.cost) lines.push("", ...renderCost(stats));
+	if (params.models) lines.push("", ...renderModels({
+		models: stats.models,
+		limit: params.limit
+	}));
+	return lines.join("\n");
+}
+function renderCost(stats) {
+	const rows = [
+		["cost", `~${formatUsd(stats.cost.totalUsd)}`],
+		["  tokens", formatUsd(stats.cost.tokensUsd)],
+		["  search fees", formatUsd(stats.cost.searchUsd)],
+		["input", compact(stats.tokens.input)],
+		["cached input", compact(stats.tokens.cachedInput)],
+		["output", compact(stats.tokens.output)],
+		["search calls", compact(stats.searchCalls)]
+	];
+	if (stats.unpricedSearches > 0) rows.push(["unpriced searches", compact(stats.unpricedSearches)]);
+	return ["COST & TOKENS", ...rows.map(([label, value]) => `  ${label.padEnd(20)}${value}`)];
+}
+function renderModels(params) {
+	const { models, limit } = params;
+	if (models.length === 0) return ["MODELS", "  no searches"];
+	const shown = limit === void 0 ? models : models.slice(0, limit);
+	const rest = models.length - shown.length;
+	return [
+		"MODELS",
+		tableRow({
+			name: "model",
+			searches: "searches",
+			tokens: "tokens",
+			cost: "cost"
+		}),
+		...shown.map((model) => tableRow({
+			name: modelName(model),
+			searches: compact(model.searches),
+			tokens: compact(model.tokens),
+			cost: model.unpricedSearches === model.searches ? "-" : formatUsd(model.costUsd)
+		})),
+		...rest > 0 ? ["", `+${rest.toLocaleString("en-US")} more model${rest === 1 ? "" : "s"}`] : []
+	];
+}
+function modelName(model) {
+	const name = model.model?.replace(/\p{Cc}/gu, "");
+	return name ? `${model.provider}/${name}` : model.provider;
+}
+function tableRow(cells) {
+	return `${(cells.name.length <= 34 ? cells.name : `${cells.name.slice(0, 33)}…`).padEnd(34)}${cells.searches.padStart(10)}${cells.tokens.padStart(10)}${cells.cost.padStart(12)}`;
+}
+/** 1234 → "1.2k", 2_000_000 → "2m". */
+function compact(value) {
+	if (value >= 1e9) return `${oneDecimal(value / 1e9)}b`;
+	if (value >= 1e6) return `${oneDecimal(value / 1e6)}m`;
+	if (value >= 1e3) return `${oneDecimal(value / 1e3)}k`;
+	return Math.round(value).toLocaleString("en-US");
+}
+function oneDecimal(value) {
+	return value.toFixed(1).replace(/\.0$/, "");
+}
+function plural(params) {
+	const noun = params.value === 1 ? params.singular : params.pluralForm ?? `${params.singular}s`;
+	return `${compact(params.value)} ${noun}`;
+}
+//#endregion
+//#region src/cli/commands/stats.ts
+/** Validate CLI options into a stats request. Pure apart from reading `now`. */
+function toStatsRequest(params) {
+	const { options } = params;
+	if ([
+		options.days !== void 0,
+		options.year !== void 0,
+		options.all
+	].filter(Boolean).length > 1) throw new WebseekError({
+		code: "invalid_usage",
+		message: "--days, --year, and --all cannot be combined."
+	});
+	return {
+		range: resolveStatsRange({
+			days: options.days === void 0 ? void 0 : parseInteger({
+				name: "days",
+				value: options.days,
+				min: 0,
+				max: 36500
+			}),
+			year: options.year === void 0 ? void 0 : parseInteger({
+				name: "year",
+				value: options.year,
+				min: 1970,
+				max: 9999
+			}),
+			all: options.all,
+			now: params.now
+		}),
+		provider: options.provider === void 0 ? void 0 : coerceProvider(options.provider),
+		cost: Boolean(options.cost || options.full),
+		models: Boolean(options.models || options.full),
+		limit: options.limit === void 0 ? void 0 : parseInteger({
+			name: "limit",
+			value: options.limit,
+			min: 1,
+			max: Number.MAX_SAFE_INTEGER
+		}),
+		json: Boolean(options.json)
+	};
+}
+function parseInteger(params) {
+	const { name, value, min, max } = params;
+	const parsed = Number(value);
+	if (!/^\d+$/.test(value.trim()) || !Number.isSafeInteger(parsed) || parsed < min || parsed > max) throw new WebseekError({
+		code: "invalid_usage",
+		message: `--${name} must be an integer between ${min} and ${max}.`
+	});
+	return parsed;
+}
+async function runStatsCommand(params) {
+	const request = toStatsRequest({ options: params.options });
+	const stats = aggregateUsage({
+		records: await readUsageRecords({ env: params.env }),
+		range: request.range,
+		provider: request.provider
+	});
+	if (request.json) {
+		const models = request.limit === void 0 ? stats.models : stats.models.slice(0, request.limit);
+		params.logger.result(JSON.stringify({
+			...stats,
+			models
+		}, null, 2));
+		return;
+	}
+	params.logger.result(renderStats({
+		stats,
+		label: request.range.label,
+		scope: request.provider ?? "all providers",
+		cost: request.cost,
+		models: request.models,
+		limit: request.limit
+	}));
+}
+function registerStatsCommand(program) {
+	program.command("stats").description("Show usage and estimated cost of the searches recorded locally").option("--days <n>", "show the last N days; 0 means today").option("--year <year>", "show a calendar year").option("--all", "show lifetime statistics").option("-p, --provider <name>", "only count one provider: openai | google | gemini").option("--cost", "show cost and token details").option("--models", "show usage per model").option("--full", "show every detailed section").option("--limit <n>", "number of rows in the models section").option("--json", "output statistics as JSON").action(wrapCommand(async ({ logger }, options) => {
+		await runStatsCommand({
+			logger,
+			options
+		});
+	}));
+}
+//#endregion
 //#region src/cli/index.ts
 /**
 * webseek CLI entry point.
@@ -207,6 +613,7 @@ function registerSearchCommand(program) {
 * Two modes:
 *   webseek <query> --provider <name>   run a one-off web search (root command)
 *   webseek mcp                         start the MCP server (stdio)
+*   webseek stats                       summarize the locally recorded usage
 */
 function readPackageVersion(dir) {
 	try {
@@ -228,12 +635,13 @@ function getVersion() {
 function buildProgram() {
 	const program = new Command();
 	const version = getVersion();
-	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version");
+	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version").enablePositionalOptions();
 	registerSearchCommand(program);
 	registerMcpCommand({
 		program,
 		version
 	});
+	registerStatsCommand(program);
 	return program;
 }
 async function main() {

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_tools = require("./tools-40nYFbvw.cjs");
+const require_tools = require("./tools-Brr43TiA.cjs");
 exports.GEMINI_BACKENDS = require_tools.GEMINI_BACKENDS;
 exports.PROVIDER_NAMES = require_tools.PROVIDER_NAMES;
 exports.WebseekError = require_tools.WebseekError;

package/dist/index.d.cts

@@ -206,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;

package/dist/index.d.mts

@@ -206,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;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-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";
+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-B4VbXLvm.mjs → tools-1ZllUYBx.mjs}

@@ -791,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)

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

@@ -791,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webseek",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Unified multi-provider web search as a CLI, MCP server, and library (OpenAI, Google Custom Search, Gemini)",
   "keywords": [
     "web-search",
@@ -54,18 +54,18 @@
     "access": "public"
   },
   "devDependencies": {
-    "@openrouter/sdk": "1.3.21",
-    "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+    "@openrouter/sdk": "1.4.12",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.6",
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^26.0.0",
-    "cspell": "10.3.3",
-    "lint-staged": "17.5.1",
-    "oxfmt": "0.70.0",
-    "oxlint": "1.85.0",
+    "cspell": "10.3.6",
+    "lint-staged": "17.6.0",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
     "repomix": "1.18.1",
-    "resend": "6.28.1",
-    "rulesync": "^17.0.0",
-    "secretlint": "13.0.5",
+    "resend": "6.31.0",
+    "rulesync": "^24.0.0",
+    "secretlint": "13.0.6",
     "simple-git-hooks": "2.14.0",
     "smol-toml": "1.9.0",
     "tsdown": "^0.23.0",