webseek 0.1.0

package/dist/tools-CCqL3Phx.mjs

@@ -0,0 +1,550 @@
+import { z } from "zod";
+//#region src/utils/error.ts
+var WebseekError = class extends Error {
+	code;
+	constructor(options) {
+		super(options.message, { cause: options.cause });
+		this.name = "WebseekError";
+		this.code = options.code;
+	}
+};
+/**
+* Map a thrown value to a process exit code: `2` for usage mistakes, `1` for
+* any other failure.
+*/
+function errorExitCode(error) {
+	if (error instanceof WebseekError) return error.code === "invalid_usage" ? 2 : 1;
+	return 1;
+}
+/** Render any thrown value into a single-line, user-facing message. */
+function formatError(error) {
+	if (error instanceof WebseekError) return `[${error.code}] ${error.message}`;
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	return JSON.stringify(error);
+}
+//#endregion
+//#region src/config/env.ts
+/**
+* Resolves provider credentials and configuration from environment variables.
+*
+* API keys are read from the environment only (never from CLI flags/args) so
+* they don't leak into shell history or process listings.
+*
+* Each provider's base URL can be overridden via an environment variable. This
+* keeps the defaults pointed at the real services while letting tests (and
+* proxies) redirect traffic to a local endpoint.
+*/
+const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
+const DEFAULT_GOOGLE_BASE_URL = "https://www.googleapis.com";
+const DEFAULT_GEMINI_BASE_URL = "https://generativelanguage.googleapis.com";
+const DEFAULT_VERTEX_BASE_URL = "https://aiplatform.googleapis.com";
+function stripTrailingSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function resolveOpenAIConfig(params = {}) {
+	const env = params.env ?? process.env;
+	const apiKey = env.OPENAI_API_KEY;
+	if (!apiKey) throw new WebseekError({
+		code: "missing_config",
+		message: "OPENAI_API_KEY is not set. Export it to use the openai provider."
+	});
+	return {
+		apiKey,
+		baseUrl: stripTrailingSlash(env.WEBSEEK_OPENAI_BASE_URL ?? DEFAULT_OPENAI_BASE_URL)
+	};
+}
+function resolveGoogleCseConfig(params = {}) {
+	const env = params.env ?? process.env;
+	const apiKey = env.GOOGLE_API_KEY;
+	const cx = env.GOOGLE_CSE_CX ?? env.GOOGLE_CSE_ID;
+	if (!apiKey) throw new WebseekError({
+		code: "missing_config",
+		message: "GOOGLE_API_KEY is not set. Export it to use the google provider."
+	});
+	if (!cx) throw new WebseekError({
+		code: "missing_config",
+		message: "GOOGLE_CSE_CX is not set. Export your Programmable Search Engine ID to use the google provider."
+	});
+	return {
+		apiKey,
+		cx,
+		baseUrl: stripTrailingSlash(env.WEBSEEK_GOOGLE_BASE_URL ?? DEFAULT_GOOGLE_BASE_URL)
+	};
+}
+function resolveGeminiConfig(params) {
+	const env = params.env ?? process.env;
+	const { backend } = params;
+	if (backend === "vertex-express") {
+		const apiKey = env.VERTEX_API_KEY;
+		if (!apiKey) throw new WebseekError({
+			code: "missing_config",
+			message: "VERTEX_API_KEY is not set. Export it to use the gemini provider with the vertex-express backend."
+		});
+		return {
+			apiKey,
+			backend,
+			baseUrl: stripTrailingSlash(env.WEBSEEK_VERTEX_BASE_URL ?? DEFAULT_VERTEX_BASE_URL)
+		};
+	}
+	const apiKey = env.GEMINI_API_KEY ?? env.GOOGLE_API_KEY;
+	if (!apiKey) throw new WebseekError({
+		code: "missing_config",
+		message: "GEMINI_API_KEY is not set. Export it to use the gemini provider."
+	});
+	return {
+		apiKey,
+		backend,
+		baseUrl: stripTrailingSlash(env.WEBSEEK_GEMINI_BASE_URL ?? DEFAULT_GEMINI_BASE_URL)
+	};
+}
+//#endregion
+//#region src/providers/gemini.ts
+/**
+* Gemini web search provider via "Grounding with Google Search".
+*
+* Grounded provider: the model runs searches and returns an answer plus
+* grounding metadata (sources + the queries it ran).
+*
+* Two backends share the same `generateContent` request/response shape; only
+* the host, auth style, and the search-tool field name differ:
+* - `gemini-api`     → generativelanguage.googleapis.com, `x-goog-api-key`,
+*                      tool field `google_search` (snake_case).
+* - `vertex-express` → aiplatform.googleapis.com, `?key=`, tool field
+*                      `googleSearch` (camelCase).
+*
+* We deliberately use the classic `generateContent` endpoint (response carries
+* `groundingMetadata`) rather than the newer Interactions API.
+*
+* Docs: https://ai.google.dev/gemini-api/docs/google-search
+*       https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search
+*/
+const DEFAULT_MODEL$1 = "gemini-2.5-flash";
+const BACKENDS = {
+	"gemini-api": {
+		searchToolField: "google_search",
+		buildRequest: ({ model, apiKey, baseUrl }) => ({
+			url: `${baseUrl}/v1beta/models/${model}:generateContent`,
+			headers: {
+				"x-goog-api-key": apiKey,
+				"content-type": "application/json"
+			}
+		})
+	},
+	"vertex-express": {
+		searchToolField: "googleSearch",
+		buildRequest: ({ model, apiKey, baseUrl }) => ({
+			url: `${baseUrl}/v1/publishers/google/models/${model}:generateContent?key=${encodeURIComponent(apiKey)}`,
+			headers: { "content-type": "application/json" }
+		})
+	}
+};
+const webSchema = z.looseObject({
+	uri: z.string().optional(),
+	title: z.string().optional()
+});
+const groundingMetadataSchema = z.looseObject({
+	webSearchQueries: z.array(z.string()).optional(),
+	groundingChunks: z.array(z.looseObject({ web: webSchema.optional() })).optional()
+});
+const candidateSchema = z.looseObject({
+	content: z.looseObject({ parts: z.array(z.looseObject({ text: z.string().optional() })).optional() }).optional(),
+	groundingMetadata: groundingMetadataSchema.optional()
+});
+const responseSchema$2 = z.looseObject({
+	candidates: z.array(candidateSchema).optional(),
+	error: z.looseObject({ message: z.string().optional() }).optional()
+});
+function createGeminiProvider(params) {
+	const { config } = params;
+	const wire = BACKENDS[config.backend];
+	return {
+		name: "gemini",
+		async search(searchParams) {
+			const fetchImpl = searchParams.fetchImpl ?? fetch;
+			const model = searchParams.model ?? DEFAULT_MODEL$1;
+			const { url, headers } = wire.buildRequest({
+				model,
+				apiKey: config.apiKey,
+				baseUrl: config.baseUrl
+			});
+			const response = await fetchImpl(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({
+					contents: [{ parts: [{ text: searchParams.query }] }],
+					tools: [{ [wire.searchToolField]: {} }]
+				})
+			});
+			const body = await response.json().catch(() => void 0);
+			const parsed = responseSchema$2.safeParse(body);
+			if (!response.ok || !parsed.success) throw toError$2({
+				status: response.status,
+				body
+			});
+			const { answer, citations, searchQueries } = extract$1(parsed.data);
+			return {
+				provider: "gemini",
+				query: searchParams.query,
+				results: [],
+				answer,
+				citations,
+				searchQueries,
+				raw: searchParams.includeRaw ? body : void 0
+			};
+		}
+	};
+}
+function extract$1(data) {
+	const candidate = data.candidates?.[0];
+	const answer = (candidate?.content?.parts ?? []).map((part) => part.text ?? "").join("");
+	const metadata = candidate?.groundingMetadata;
+	return {
+		answer,
+		citations: (metadata?.groundingChunks ?? []).map((chunk) => chunk.web).filter((web) => web !== void 0 && web.uri !== void 0).map((web) => ({
+			url: web.uri,
+			title: web.title
+		})),
+		searchQueries: metadata?.webSearchQueries ?? []
+	};
+}
+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}).`;
+	if (params.status === 401 || params.status === 403) return new WebseekError({
+		code: "auth_failed",
+		message
+	});
+	if (params.status === 429) return new WebseekError({
+		code: "rate_limited",
+		message
+	});
+	return new WebseekError({
+		code: "provider_error",
+		message
+	});
+}
+//#endregion
+//#region src/providers/google-cse.ts
+/**
+* Google Custom Search (Programmable Search Engine) JSON API provider.
+*
+* This is a SERP-style provider: it returns a ranked list of links.
+*
+* NOTE: The Custom Search JSON API is closed to new customers; existing
+* customers must migrate before 2027-01-01. See the README for details.
+*
+* Docs: https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list
+*/
+const PATH$1 = "/customsearch/v1";
+/** Max results the API returns per request, and the hard cap on total results. */
+const MAX_PER_REQUEST = 10;
+const MAX_TOTAL_RESULTS = 100;
+const itemSchema = z.looseObject({
+	title: z.string().optional(),
+	link: z.string().optional(),
+	snippet: z.string().optional(),
+	displayLink: z.string().optional()
+});
+const responseSchema$1 = z.looseObject({
+	items: z.array(itemSchema).optional(),
+	error: z.looseObject({
+		code: z.number().optional(),
+		message: z.string().optional()
+	}).optional()
+});
+function createGoogleCseProvider(params) {
+	const { config } = params;
+	return {
+		name: "google",
+		async search(searchParams) {
+			const fetchImpl = searchParams.fetchImpl ?? fetch;
+			const desired = clampDesired(searchParams.maxResults ?? MAX_PER_REQUEST);
+			const items = [];
+			let lastRaw;
+			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({
+					config,
+					query: searchParams.query,
+					start,
+					num
+				}));
+				const body = await response.json().catch(() => void 0);
+				lastRaw = body;
+				const parsed = responseSchema$1.safeParse(body);
+				if (!response.ok || !parsed.success) throw toError$1({
+					status: response.status,
+					body: parsed.success ? parsed.data : body
+				});
+				const page = parsed.data.items ?? [];
+				items.push(...page);
+				if (page.length < num) break;
+			}
+			return {
+				provider: "google",
+				query: searchParams.query,
+				results: items.slice(0, desired).map((item) => ({
+					title: item.title ?? "",
+					url: item.link ?? "",
+					snippet: item.snippet ?? "",
+					displayLink: item.displayLink
+				})),
+				citations: [],
+				searchQueries: [searchParams.query],
+				raw: searchParams.includeRaw ? lastRaw : void 0
+			};
+		}
+	};
+}
+function clampDesired(value) {
+	if (!Number.isFinite(value) || value < 1) return MAX_PER_REQUEST;
+	return Math.min(Math.floor(value), MAX_TOTAL_RESULTS);
+}
+function buildUrl(params) {
+	const url = new URL(`${params.config.baseUrl}${PATH$1}`);
+	url.searchParams.set("key", params.config.apiKey);
+	url.searchParams.set("cx", params.config.cx);
+	url.searchParams.set("q", params.query);
+	url.searchParams.set("num", String(params.num));
+	url.searchParams.set("start", String(params.start));
+	return url.toString();
+}
+function toError$1(params) {
+	const message = extractMessage(params.body) ?? `Google Custom Search request failed (HTTP ${params.status}).`;
+	if (params.status === 401 || params.status === 403) return new WebseekError({
+		code: "auth_failed",
+		message
+	});
+	if (params.status === 429) return new WebseekError({
+		code: "rate_limited",
+		message
+	});
+	return new WebseekError({
+		code: "provider_error",
+		message
+	});
+}
+function extractMessage(body) {
+	const parsed = responseSchema$1.safeParse(body);
+	return parsed.success ? parsed.data.error?.message : void 0;
+}
+//#endregion
+//#region src/providers/openai.ts
+/**
+* OpenAI web search provider (Responses API `web_search` tool).
+*
+* This is a grounded provider: the model runs searches and returns a
+* synthesized answer plus `url_citation` annotations.
+*
+* Docs: https://developers.openai.com/api/docs/guides/tools-web-search
+*/
+const PATH = "/v1/responses";
+const DEFAULT_MODEL = "gpt-5.5";
+const annotationSchema = z.looseObject({
+	type: z.string().optional(),
+	url: z.string().optional(),
+	title: z.string().optional(),
+	start_index: z.number().optional(),
+	end_index: z.number().optional()
+});
+const contentSchema = z.looseObject({
+	type: z.string().optional(),
+	text: z.string().optional(),
+	annotations: z.array(annotationSchema).optional()
+});
+const outputItemSchema = z.looseObject({
+	type: z.string().optional(),
+	content: z.array(contentSchema).optional(),
+	action: z.looseObject({ query: z.string().optional() }).optional()
+});
+const responseSchema = z.looseObject({
+	output: z.array(outputItemSchema).optional(),
+	output_text: z.string().optional(),
+	error: z.looseObject({ message: z.string().optional() }).optional()
+});
+function createOpenAIProvider(params) {
+	const { config } = params;
+	return {
+		name: "openai",
+		async search(searchParams) {
+			const fetchImpl = searchParams.fetchImpl ?? fetch;
+			const model = searchParams.model ?? DEFAULT_MODEL;
+			const response = await fetchImpl(`${config.baseUrl}${PATH}`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${config.apiKey}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({
+					model,
+					tools: [{ type: "web_search" }],
+					input: searchParams.query
+				})
+			});
+			const body = await response.json().catch(() => void 0);
+			const parsed = responseSchema.safeParse(body);
+			if (!response.ok || !parsed.success) throw toError({
+				status: response.status,
+				body
+			});
+			const { answer, citations, searchQueries } = extract(parsed.data);
+			return {
+				provider: "openai",
+				query: searchParams.query,
+				results: [],
+				answer,
+				citations,
+				searchQueries,
+				raw: searchParams.includeRaw ? body : void 0
+			};
+		}
+	};
+}
+function extract(data) {
+	const textParts = [];
+	const citations = [];
+	const searchQueries = [];
+	for (const item of data.output ?? []) {
+		if (item.type === "web_search_call" && 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({
+				url: annotation.url,
+				title: annotation.title,
+				startIndex: annotation.start_index,
+				endIndex: annotation.end_index
+			});
+		}
+	}
+	return {
+		answer: textParts.length > 0 ? textParts.join("") : data.output_text ?? "",
+		citations,
+		searchQueries
+	};
+}
+function toError(params) {
+	const parsed = responseSchema.safeParse(params.body);
+	const message = (parsed.success ? parsed.data.error?.message : void 0) ?? `OpenAI web search request failed (HTTP ${params.status}).`;
+	if (params.status === 401) return new WebseekError({
+		code: "auth_failed",
+		message
+	});
+	if (params.status === 429) return new WebseekError({
+		code: "rate_limited",
+		message
+	});
+	return new WebseekError({
+		code: "provider_error",
+		message
+	});
+}
+//#endregion
+//#region src/lib/search.ts
+const PROVIDER_NAMES = [
+	"openai",
+	"google",
+	"gemini"
+];
+const GEMINI_BACKENDS = ["gemini-api", "vertex-express"];
+/** Validate an arbitrary string as a provider name, or throw a usage error. */
+function coerceProvider(value) {
+	if (typeof value === "string" && PROVIDER_NAMES.includes(value)) return value;
+	throw new WebseekError({
+		code: "invalid_usage",
+		message: `Invalid provider. Choose one of: ${PROVIDER_NAMES.join(", ")}.`
+	});
+}
+/** Validate an arbitrary string as a Gemini backend, or throw a usage error. */
+function coerceGeminiBackend(value) {
+	if (typeof value === "string" && GEMINI_BACKENDS.includes(value)) return value;
+	throw new WebseekError({
+		code: "invalid_usage",
+		message: `Invalid gemini backend. Choose one of: ${GEMINI_BACKENDS.join(", ")}.`
+	});
+}
+/** Validate a max-results value as a positive integer, or throw a usage error. */
+function coerceMaxResults(value) {
+	const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new WebseekError({
+		code: "invalid_usage",
+		message: "max-results must be a positive integer."
+	});
+	return parsed;
+}
+function runSearch(params) {
+	return resolveProvider(params).search({
+		query: params.query,
+		maxResults: params.maxResults,
+		model: params.model,
+		includeRaw: params.includeRaw,
+		fetchImpl: params.fetchImpl
+	});
+}
+function resolveProvider(params) {
+	switch (params.provider) {
+		case "openai": return createOpenAIProvider({ config: resolveOpenAIConfig({ env: params.env }) });
+		case "google": return createGoogleCseProvider({ config: resolveGoogleCseConfig({ env: params.env }) });
+		case "gemini": return createGeminiProvider({ config: resolveGeminiConfig({
+			env: params.env,
+			backend: params.geminiBackend ?? "gemini-api"
+		}) });
+		default: throw new WebseekError({
+			code: "invalid_usage",
+			message: `Unknown provider: ${String(params.provider)}`
+		});
+	}
+}
+//#endregion
+//#region src/mcp/tools.ts
+/**
+* The `web_search` MCP tool. It is the MCP-mode counterpart to the CLI `search`
+* command: both validate their inputs and call the same `runSearch` core.
+*/
+const webSearchInputShape = {
+	query: z.string().min(1).describe("The search query."),
+	provider: z.enum(PROVIDER_NAMES).describe("Which provider to search with."),
+	maxResults: z.number().int().positive().optional().describe("Desired number of results (SERP providers; best-effort otherwise)."),
+	model: z.string().optional().describe("Model override for LLM-backed providers."),
+	geminiBackend: z.enum(GEMINI_BACKENDS).optional().describe("Gemini backend: gemini-api (default) or vertex-express."),
+	includeRaw: z.boolean().optional().describe("Include the provider's raw response.")
+};
+z.object(webSearchInputShape);
+function createWebSearchTool(params = {}) {
+	return {
+		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.",
+			inputSchema: webSearchInputShape
+		},
+		handler: async (args) => {
+			try {
+				const result = await runSearch({
+					provider: args.provider,
+					query: args.query,
+					maxResults: args.maxResults,
+					model: args.model,
+					geminiBackend: args.geminiBackend,
+					includeRaw: args.includeRaw,
+					env: params.env,
+					fetchImpl: params.fetchImpl
+				});
+				return { content: [{
+					type: "text",
+					text: JSON.stringify(result, null, 2)
+				}] };
+			} catch (error) {
+				return {
+					content: [{
+						type: "text",
+						text: formatError(error)
+					}],
+					isError: true
+				};
+			}
+		}
+	};
+}
+//#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 };