@amaranthic/hernex 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/CHANGELOG.md +79 -0
  2. package/README.md +1 -1
  3. package/dist/engine/runTurn.d.ts.map +1 -1
  4. package/dist/engine/runTurn.js +3 -0
  5. package/dist/engine/runTurn.js.map +1 -1
  6. package/dist/index.d.ts +2 -2
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/tools/ToolExecutionContext.d.ts +13 -0
  11. package/dist/tools/ToolExecutionContext.d.ts.map +1 -1
  12. package/dist/tools/ToolRegistry.d.ts +3 -3
  13. package/dist/tools/ToolRegistry.d.ts.map +1 -1
  14. package/dist/tools/ToolRegistry.js +5 -1
  15. package/dist/tools/ToolRegistry.js.map +1 -1
  16. package/dist/tools/WebFetchTool.d.ts +126 -0
  17. package/dist/tools/WebFetchTool.d.ts.map +1 -0
  18. package/dist/tools/WebFetchTool.js +374 -0
  19. package/dist/tools/WebFetchTool.js.map +1 -0
  20. package/dist/tools/WebSearchTool.d.ts +181 -0
  21. package/dist/tools/WebSearchTool.d.ts.map +1 -0
  22. package/dist/tools/WebSearchTool.js +207 -0
  23. package/dist/tools/WebSearchTool.js.map +1 -0
  24. package/dist/tools/index.d.ts +3 -0
  25. package/dist/tools/index.d.ts.map +1 -1
  26. package/dist/tools/index.js +3 -0
  27. package/dist/tools/index.js.map +1 -1
  28. package/dist/tools/internal/duckDuckGo.d.ts +217 -0
  29. package/dist/tools/internal/duckDuckGo.d.ts.map +1 -0
  30. package/dist/tools/internal/duckDuckGo.js +535 -0
  31. package/dist/tools/internal/duckDuckGo.js.map +1 -0
  32. package/dist/tools/internal/ssrfGuard.d.ts +38 -0
  33. package/dist/tools/internal/ssrfGuard.d.ts.map +1 -0
  34. package/dist/tools/internal/ssrfGuard.js +155 -0
  35. package/dist/tools/internal/ssrfGuard.js.map +1 -0
  36. package/dist/tools/prompts.d.ts +8 -0
  37. package/dist/tools/prompts.d.ts.map +1 -1
  38. package/dist/tools/prompts.js +14 -0
  39. package/dist/tools/prompts.js.map +1 -1
  40. package/package.json +4 -1
@@ -0,0 +1,374 @@
1
+ /**
2
+ * @fileoverview Built-in tool for fetching web page content and converting to Markdown.
3
+ * Features SSRF protection (ipaddr.js), cross-host redirect detection, 15-minute in-memory caching,
4
+ * HTML conversion via Turndown, and optional focused extraction using Hernex generateText.
5
+ * @packageDocumentation
6
+ */
7
+ import TurndownService from "turndown";
8
+ import { z } from "zod";
9
+ import { isPermittedRedirect, validateWebUrl } from "./internal/ssrfGuard.js";
10
+ import { webFetchDescription } from "./prompts.js";
11
+ import { generateText } from "../runtime.js";
12
+ /**
13
+ * Maximum character count returned before truncating web content output.
14
+ */
15
+ const maxWebFetchCharacters = 150000;
16
+ /**
17
+ * Default maximum redirects permitted per fetch invocation.
18
+ */
19
+ const defaultMaxRedirects = 5;
20
+ /**
21
+ * Default request timeout in milliseconds (15 seconds).
22
+ */
23
+ const defaultTimeoutMs = 15000;
24
+ /**
25
+ * Default cache time-to-live in milliseconds (15 minutes).
26
+ */
27
+ const defaultCacheTtlMs = 15 * 60 * 1000;
28
+ /**
29
+ * Default maximum response body size in bytes (5 MB).
30
+ */
31
+ const defaultMaxResponseBytes = 5 * 1024 * 1024;
32
+ /**
33
+ * Maximum extraction retry attempts for Hernex generateText.
34
+ */
35
+ const maxExtractionRetries = 5;
36
+ /**
37
+ * Initial backoff delay for extraction retries in milliseconds.
38
+ */
39
+ const initialExtractionDelayMs = 500;
40
+ /**
41
+ * Default system instructions for secondary prompt extraction.
42
+ */
43
+ const defaultExtractionInstructions = "You are a web content analysis assistant. Your task is to extract, analyze, or summarize " +
44
+ "the provided webpage content in direct response to the user's request.\n" +
45
+ "Base your answer strictly on the provided content. If the content does not contain sufficient " +
46
+ "information to answer the request, state that clearly without guessing or fabricating facts.";
47
+ /**
48
+ * Input parameter schema for WebFetchTool.
49
+ */
50
+ export const webFetchInputSchema = z.object({
51
+ url: z
52
+ .string()
53
+ .url()
54
+ .describe("The HTTP or HTTPS URL of the webpage or resource to fetch."),
55
+ prompt: z
56
+ .string()
57
+ .optional()
58
+ .describe("Optional question or instruction to extract specific information from the fetched webpage. " +
59
+ "If omitted, returns the page content converted to Markdown."),
60
+ });
61
+ /**
62
+ * Executes an async operation with up to maxRetries attempts using exponential backoff.
63
+ *
64
+ * @param operation - The asynchronous function to execute.
65
+ * @param maxRetries - Maximum retry attempts after an initial failure.
66
+ * @param initialDelayMs - Base delay in milliseconds before exponential scaling.
67
+ * @param abortSignal - Optional signal to abort wait delays immediately.
68
+ * @returns The resolved result of the operation.
69
+ */
70
+ async function executeWithRetry(operation, maxRetries, initialDelayMs, abortSignal) {
71
+ let attempt = 0;
72
+ let delay = initialDelayMs;
73
+ while (true) {
74
+ if (abortSignal?.aborted) {
75
+ throw abortSignal.reason ?? new Error("Operation aborted");
76
+ }
77
+ try {
78
+ return await operation();
79
+ }
80
+ catch (error) {
81
+ attempt++;
82
+ if (attempt > maxRetries || abortSignal?.aborted) {
83
+ throw error;
84
+ }
85
+ await new Promise((resolve, reject) => {
86
+ const timer = setTimeout(resolve, delay);
87
+ if (abortSignal) {
88
+ const onAbort = () => {
89
+ clearTimeout(timer);
90
+ abortSignal.removeEventListener("abort", onAbort);
91
+ reject(abortSignal.reason ?? new Error("Operation aborted"));
92
+ };
93
+ abortSignal.addEventListener("abort", onAbort, { once: true });
94
+ }
95
+ });
96
+ delay = Math.min(delay * 2, 8000);
97
+ }
98
+ }
99
+ }
100
+ /**
101
+ * Built-in agent tool for fetching external web pages and converting them to Markdown.
102
+ *
103
+ * Implements strict SSRF protection against private or loopback networks, detects
104
+ * cross-host redirects to preserve agent control, maintains a 15-minute response cache,
105
+ * and enables optional model extraction via Hernex's generateText runtime.
106
+ */
107
+ export class WebFetchTool {
108
+ static toolName = "webFetch";
109
+ name = WebFetchTool.toolName;
110
+ description = webFetchDescription;
111
+ inputSchema = webFetchInputSchema;
112
+ maxRedirects;
113
+ timeoutMs;
114
+ cacheTtlMs;
115
+ maxResponseBytes;
116
+ fetchFn;
117
+ turndown;
118
+ cache = new Map();
119
+ /**
120
+ * Constructs a new WebFetchTool instance with configurable options.
121
+ *
122
+ * @param options - Optional configuration parameters.
123
+ */
124
+ constructor(options) {
125
+ this.maxRedirects = options?.maxRedirects ?? defaultMaxRedirects;
126
+ this.timeoutMs = options?.timeoutMs ?? defaultTimeoutMs;
127
+ this.cacheTtlMs = options?.cacheTtlMs ?? defaultCacheTtlMs;
128
+ this.maxResponseBytes =
129
+ options?.maxResponseBytes ?? defaultMaxResponseBytes;
130
+ this.fetchFn = options?.customFetch ?? globalThis.fetch;
131
+ this.turndown = new TurndownService({
132
+ headingStyle: "atx",
133
+ codeBlockStyle: "fenced",
134
+ hr: "---",
135
+ bulletListMarker: "-",
136
+ emDelimiter: "_",
137
+ strongDelimiter: "**",
138
+ });
139
+ this.turndown.remove([
140
+ "script",
141
+ "style",
142
+ "noscript",
143
+ "svg",
144
+ "iframe",
145
+ "canvas",
146
+ ]);
147
+ }
148
+ /**
149
+ * Converts HTML text into clean Markdown using TurndownService.
150
+ *
151
+ * @param html - Raw HTML response body string.
152
+ * @returns Cleaned Markdown text.
153
+ */
154
+ convertHtmlToMarkdown(html) {
155
+ const cleaned = html
156
+ .replace(/<!--[\s\S]*?-->/g, "")
157
+ .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "")
158
+ .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, "");
159
+ const markdown = this.turndown.turndown(cleaned);
160
+ return markdown.replace(/\n{3,}/g, "\n\n").trim();
161
+ }
162
+ /**
163
+ * Normalizes raw response text based on content type.
164
+ *
165
+ * @param rawText - The raw response body text.
166
+ * @param contentType - The Content-Type header value.
167
+ * @returns Formatted Markdown or text.
168
+ */
169
+ formatContentByMimeType(rawText, contentType) {
170
+ const lowerType = contentType.toLowerCase();
171
+ if (lowerType.includes("text/html") ||
172
+ lowerType.includes("application/xhtml+xml")) {
173
+ return this.convertHtmlToMarkdown(rawText);
174
+ }
175
+ if (lowerType.includes("application/json")) {
176
+ try {
177
+ const parsed = JSON.parse(rawText);
178
+ return `\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``;
179
+ }
180
+ catch {
181
+ return rawText.trim();
182
+ }
183
+ }
184
+ if (lowerType.startsWith("image/") ||
185
+ lowerType.startsWith("video/") ||
186
+ lowerType.startsWith("audio/") ||
187
+ lowerType.includes("application/pdf") ||
188
+ lowerType.includes("application/zip") ||
189
+ lowerType.includes("application/octet-stream")) {
190
+ return `[Binary content of type '${contentType}' received. WebFetch converts text and HTML to Markdown.]`;
191
+ }
192
+ return rawText.trim();
193
+ }
194
+ /**
195
+ * Fetches the resource across allowed redirects while checking SSRF constraints.
196
+ *
197
+ * @param initialUrl - The validated initial URL.
198
+ * @param abortSignal - Optional signal to abort the fetch operation.
199
+ * @returns An object containing the final URL, status, contentType, and raw text body.
200
+ */
201
+ async performFetch(initialUrl, abortSignal) {
202
+ let currentUrl = initialUrl.toString();
203
+ let redirectCount = 0;
204
+ while (redirectCount <= this.maxRedirects) {
205
+ validateWebUrl(currentUrl);
206
+ const controller = new AbortController();
207
+ let combinedSignal;
208
+ if (abortSignal) {
209
+ const onAbort = () => controller.abort(abortSignal.reason);
210
+ abortSignal.addEventListener("abort", onAbort, { once: true });
211
+ const timer = setTimeout(() => controller.abort(new Error("Web fetch timed out.")), this.timeoutMs);
212
+ combinedSignal = controller.signal;
213
+ combinedSignal.addEventListener("abort", () => clearTimeout(timer), {
214
+ once: true,
215
+ });
216
+ }
217
+ else {
218
+ const timer = setTimeout(() => controller.abort(new Error("Web fetch timed out.")), this.timeoutMs);
219
+ combinedSignal = controller.signal;
220
+ combinedSignal.addEventListener("abort", () => clearTimeout(timer), {
221
+ once: true,
222
+ });
223
+ }
224
+ const response = await this.fetchFn(currentUrl, {
225
+ method: "GET",
226
+ headers: {
227
+ Accept: "text/html,application/xhtml+xml,application/json,text/plain;q=0.9,*/*;q=0.8",
228
+ "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Hernex/0.3 WebFetch",
229
+ },
230
+ redirect: "manual",
231
+ signal: combinedSignal,
232
+ });
233
+ const isRedirect = response.status >= 300 &&
234
+ response.status < 400 &&
235
+ response.headers.has("location");
236
+ if (isRedirect) {
237
+ const location = response.headers.get("location");
238
+ const targetUrl = new URL(location, currentUrl).toString();
239
+ if (!isPermittedRedirect(currentUrl, targetUrl)) {
240
+ return {
241
+ finalUrl: currentUrl,
242
+ status: response.status,
243
+ contentType: response.headers.get("content-type") ?? "text/plain",
244
+ bodyText: "",
245
+ crossHostRedirect: targetUrl,
246
+ };
247
+ }
248
+ currentUrl = targetUrl;
249
+ redirectCount++;
250
+ continue;
251
+ }
252
+ const contentType = response.headers.get("content-type") ?? "text/plain; charset=utf-8";
253
+ const contentLengthHeader = response.headers.get("content-length");
254
+ if (contentLengthHeader) {
255
+ const length = parseInt(contentLengthHeader, 10);
256
+ if (!isNaN(length) && length > this.maxResponseBytes) {
257
+ throw new Error(`Response size (${(length / (1024 * 1024)).toFixed(1)}MB) exceeds maximum allowed size of ${(this.maxResponseBytes / (1024 * 1024)).toFixed(1)}MB.`);
258
+ }
259
+ }
260
+ const bodyText = await response.text();
261
+ if (bodyText.length > this.maxResponseBytes) {
262
+ throw new Error(`Response body size exceeds maximum allowed size of ${(this.maxResponseBytes / (1024 * 1024)).toFixed(1)}MB.`);
263
+ }
264
+ return {
265
+ finalUrl: currentUrl,
266
+ status: response.status,
267
+ contentType,
268
+ bodyText,
269
+ };
270
+ }
271
+ throw new Error(`Maximum redirect limit of ${this.maxRedirects} hops exceeded.`);
272
+ }
273
+ /**
274
+ * Executes the web fetch operation with SSRF validation, caching, and optional extraction.
275
+ *
276
+ * @param parameters - Validated parameters containing url and optional prompt.
277
+ * @param context - The execution context with model, credentials, and abortSignal.
278
+ * @returns A promise resolving to the structured web fetch output.
279
+ */
280
+ async execute(parameters, context) {
281
+ const startTime = Date.now();
282
+ const validatedUrl = validateWebUrl(parameters.url);
283
+ const cacheKey = validatedUrl.toString();
284
+ let pageData;
285
+ let isCached = false;
286
+ const existing = this.cache.get(cacheKey);
287
+ if (existing && Date.now() - existing.timestamp < this.cacheTtlMs) {
288
+ pageData = existing;
289
+ isCached = true;
290
+ }
291
+ if (!pageData) {
292
+ const fetchResult = await this.performFetch(validatedUrl, context.abortSignal);
293
+ if (fetchResult.crossHostRedirect) {
294
+ const redirectMessage = `Redirect detected to: ${fetchResult.crossHostRedirect}. ` +
295
+ "Automatic cross-host redirect halted for security and oversight. " +
296
+ "Call webFetch with this new URL if desired.";
297
+ return {
298
+ url: parameters.url,
299
+ finalUrl: fetchResult.finalUrl,
300
+ status: fetchResult.status,
301
+ contentType: fetchResult.contentType,
302
+ content: redirectMessage,
303
+ cached: false,
304
+ durationMs: Date.now() - startTime,
305
+ };
306
+ }
307
+ let markdown = this.formatContentByMimeType(fetchResult.bodyText, fetchResult.contentType);
308
+ if (markdown.length > maxWebFetchCharacters) {
309
+ markdown =
310
+ markdown.slice(0, maxWebFetchCharacters) +
311
+ `\n\n... [Webpage content truncated at ${maxWebFetchCharacters.toLocaleString()} characters]`;
312
+ }
313
+ pageData = {
314
+ finalUrl: fetchResult.finalUrl,
315
+ status: fetchResult.status,
316
+ contentType: fetchResult.contentType,
317
+ markdownContent: markdown,
318
+ timestamp: Date.now(),
319
+ };
320
+ if (fetchResult.status >= 200 && fetchResult.status < 300) {
321
+ this.cache.set(cacheKey, pageData);
322
+ }
323
+ }
324
+ if (!parameters.prompt || parameters.prompt.trim().length === 0) {
325
+ return {
326
+ url: parameters.url,
327
+ finalUrl: pageData.finalUrl,
328
+ status: pageData.status,
329
+ contentType: pageData.contentType,
330
+ content: pageData.markdownContent,
331
+ cached: isCached,
332
+ durationMs: Date.now() - startTime,
333
+ extractedWithPrompt: false,
334
+ };
335
+ }
336
+ if (!context.model) {
337
+ throw new Error("Extraction with 'prompt' requires an active model in ToolExecutionContext. " +
338
+ "Ensure the tool is executed within an agent turn or provide context.model.");
339
+ }
340
+ const promptText = `Webpage URL: ${pageData.finalUrl}\n\n` +
341
+ `Webpage Content:\n${pageData.markdownContent}\n\n` +
342
+ `User Request:\n${parameters.prompt.trim()}`;
343
+ const extractionResult = await executeWithRetry(async () => {
344
+ return generateText({
345
+ model: context.model,
346
+ apiKey: context.apiKey ?? "",
347
+ baseUrl: context.baseUrl ?? "",
348
+ instructions: defaultExtractionInstructions,
349
+ prompt: promptText,
350
+ ...(context.abortSignal ? { abortSignal: context.abortSignal } : {}),
351
+ });
352
+ }, maxExtractionRetries, initialExtractionDelayMs, context.abortSignal);
353
+ return {
354
+ url: parameters.url,
355
+ finalUrl: pageData.finalUrl,
356
+ status: pageData.status,
357
+ contentType: pageData.contentType,
358
+ content: extractionResult.text.trim(),
359
+ cached: isCached,
360
+ durationMs: Date.now() - startTime,
361
+ extractedWithPrompt: true,
362
+ };
363
+ }
364
+ }
365
+ /**
366
+ * Convenience factory for creating a configured WebFetchTool instance.
367
+ *
368
+ * @param options - Optional configuration settings.
369
+ * @returns An initialized WebFetchTool instance.
370
+ */
371
+ export function createWebFetchTool(options) {
372
+ return new WebFetchTool(options);
373
+ }
374
+ //# sourceMappingURL=WebFetchTool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"WebFetchTool.js","sources":["../../src/tools/WebFetchTool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,181 @@
1
+ /**
2
+ * @fileoverview Built-in tool for web searching using a high-reliability native DuckDuckGo engine.
3
+ * Converts snippets and instant answers into clean Markdown via Turndown, unwraps redirects,
4
+ * supports pagination, SafeSearch, time ranges, domain filtering, and 15-minute response caching.
5
+ * @packageDocumentation
6
+ */
7
+ import { z } from "zod";
8
+ import type { AgentTool } from "./AgentTool.js";
9
+ import type { ToolExecutionContext } from "./ToolExecutionContext.js";
10
+ import { type DuckDuckGoInstantAnswer, type DuckDuckGoSearchResultItem } from "./internal/duckDuckGo.js";
11
+ /**
12
+ * Zod schema defining valid input parameters for WebSearchTool.
13
+ */
14
+ export declare const webSearchInputSchema: z.ZodObject<{
15
+ query: z.ZodString;
16
+ limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
17
+ offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
18
+ time: z.ZodOptional<z.ZodEnum<{
19
+ all: "all";
20
+ day: "day";
21
+ month: "month";
22
+ week: "week";
23
+ year: "year";
24
+ }>>;
25
+ safeSearch: z.ZodOptional<z.ZodEnum<{
26
+ moderate: "moderate";
27
+ off: "off";
28
+ strict: "strict";
29
+ }>>;
30
+ region: z.ZodOptional<z.ZodString>;
31
+ allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
32
+ blockedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
33
+ }, z.core.$strip>;
34
+ /**
35
+ * Inferred input type for WebSearchTool parameters.
36
+ */
37
+ export type WebSearchInput = z.infer<typeof webSearchInputSchema>;
38
+ /**
39
+ * Structured output returned by WebSearchTool upon execution.
40
+ */
41
+ export interface WebSearchOutput {
42
+ /**
43
+ * The query string that was searched.
44
+ */
45
+ readonly query: string;
46
+ /**
47
+ * Array of parsed organic search result items with clean canonical URLs.
48
+ */
49
+ readonly results: readonly DuckDuckGoSearchResultItem[];
50
+ /**
51
+ * Total number of results returned in this response batch.
52
+ */
53
+ readonly totalResults: number;
54
+ /**
55
+ * Current pagination offset.
56
+ */
57
+ readonly offset: number;
58
+ /**
59
+ * Next pagination offset index if additional result pages are available.
60
+ */
61
+ readonly nextOffset?: number | undefined;
62
+ /**
63
+ * Whether subsequent pages of search results exist.
64
+ */
65
+ readonly hasNextPage: boolean;
66
+ /**
67
+ * Whether this response was served from the in-memory cache.
68
+ */
69
+ readonly cached: boolean;
70
+ /**
71
+ * Duration of the search execution in milliseconds.
72
+ */
73
+ readonly durationMs: number;
74
+ /**
75
+ * Optional DuckDuckGo instant answer summary and Wikipedia abstract.
76
+ */
77
+ readonly instantAnswer?: DuckDuckGoInstantAnswer | undefined;
78
+ /**
79
+ * Clean Markdown representation of all search results and instant answers.
80
+ */
81
+ readonly content: string;
82
+ }
83
+ /**
84
+ * Configuration options for initializing a WebSearchTool instance.
85
+ */
86
+ export interface WebSearchToolOptions {
87
+ /**
88
+ * In-memory cache time-to-live in milliseconds. Defaults to 15 minutes.
89
+ */
90
+ readonly cacheTtlMs?: number | undefined;
91
+ /**
92
+ * Optional custom fetch implementation for testing or sandboxing.
93
+ */
94
+ readonly customFetch?: typeof fetch | undefined;
95
+ /**
96
+ * Whether to enable human-like timing jitter between queries. Defaults to true.
97
+ */
98
+ readonly enableJitter?: boolean | undefined;
99
+ }
100
+ /**
101
+ * Built-in agent tool for searching the web via DuckDuckGo with automatic URL unwrapping,
102
+ * HTML-to-Markdown conversion via Turndown, pagination, filtering, and caching.
103
+ */
104
+ export declare class WebSearchTool implements AgentTool<typeof webSearchInputSchema, WebSearchOutput> {
105
+ /**
106
+ * Unique name of the tool in the agent registry.
107
+ */
108
+ readonly name = "webSearch";
109
+ /**
110
+ * Detailed system instruction prompt describing the tool.
111
+ */
112
+ readonly description: string;
113
+ /**
114
+ * Zod input schema for parameter validation.
115
+ */
116
+ readonly inputSchema: z.ZodObject<{
117
+ query: z.ZodString;
118
+ limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
119
+ offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
120
+ time: z.ZodOptional<z.ZodEnum<{
121
+ all: "all";
122
+ day: "day";
123
+ month: "month";
124
+ week: "week";
125
+ year: "year";
126
+ }>>;
127
+ safeSearch: z.ZodOptional<z.ZodEnum<{
128
+ moderate: "moderate";
129
+ off: "off";
130
+ strict: "strict";
131
+ }>>;
132
+ region: z.ZodOptional<z.ZodString>;
133
+ allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
134
+ blockedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
135
+ }, z.core.$strip>;
136
+ /**
137
+ * In-memory cache time-to-live in milliseconds.
138
+ */
139
+ private readonly cacheTtlMs;
140
+ /**
141
+ * Custom fetch function override.
142
+ */
143
+ private readonly fetchFn?;
144
+ /**
145
+ * Whether human-like timing jitter is enabled.
146
+ */
147
+ private readonly enableJitter;
148
+ /**
149
+ * In-memory response cache mapped by normalized query key.
150
+ */
151
+ private readonly cache;
152
+ /**
153
+ * Creates a new WebSearchTool instance with optional caching and fetch overrides.
154
+ *
155
+ * @param options - Configuration options for the search tool.
156
+ */
157
+ constructor(options?: WebSearchToolOptions);
158
+ /**
159
+ * Generates a stable deterministic cache key from input parameters.
160
+ *
161
+ * @param parameters - Search input parameters.
162
+ * @returns Deterministic cache key string.
163
+ */
164
+ private getCacheKey;
165
+ /**
166
+ * Executes the web search operation, respecting in-memory caching and fail-soft semantics.
167
+ *
168
+ * @param parameters - Validated search parameters.
169
+ * @param context - The execution context with abortSignal and credentials.
170
+ * @returns A promise resolving to the structured search output.
171
+ */
172
+ execute(parameters: WebSearchInput, context: ToolExecutionContext): Promise<WebSearchOutput>;
173
+ }
174
+ /**
175
+ * Factory helper function to create a configured WebSearchTool instance.
176
+ *
177
+ * @param options - Optional configuration options for the search tool.
178
+ * @returns An initialized WebSearchTool instance.
179
+ */
180
+ export declare function createWebSearchTool(options?: WebSearchToolOptions): WebSearchTool;
181
+ //# sourceMappingURL=WebSearchTool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"WebSearchTool.d.ts","sources":["../../src/tools/WebSearchTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAGhC,MAAM,0BAA0B,CAAC;AAQlC;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;iBAoD/B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAExD;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAE7D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;IAEhD;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7C;AAUD;;;GAGG;AACH,qBAAa,aAAc,YAAW,SAAS,CAC7C,OAAO,oBAAoB,EAC3B,eAAe,CAChB;IACC;;OAEG;IACH,SAAgB,IAAI,eAAe;IAEnC;;OAEG;IACH,SAAgB,WAAW,SAAwB;IAEnD;;OAEG;IACH,SAAgB,WAAW;;;;;;;;;;;;;;;;;;;sBAAwB;IAEnD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA2B;IAEpD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IAEvC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;IAE/D;;;;OAIG;IACH,YAAmB,OAAO,CAAC,EAAE,oBAAoB,EAIhD;IAED;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAiBnB;;;;;;OAMG;IACU,OAAO,CAClB,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAyE1B;CACF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa,CAEf"}