@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,535 @@
1
+ /**
2
+ * @fileoverview High-reliability native DuckDuckGo engine for Hernex.
3
+ * Performs web search with automatic link unwrapping, HTML-to-Markdown conversion
4
+ * via Turndown, pagination, time/region filtering, stealth browser headers,
5
+ * jitter timing, and automatic fallback to lite.duckduckgo.com.
6
+ * @packageDocumentation
7
+ */
8
+ import TurndownService from "turndown";
9
+ /**
10
+ * List of realistic desktop and mobile user agents to mimic real human browsing.
11
+ */
12
+ const realisticUserAgents = [
13
+ "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
14
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
15
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
16
+ "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:132.0) Gecko/20100101 Firefox/132.0",
17
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:132.0) Gecko/20100101 Firefox/132.0",
18
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1 Safari/605.1.15",
19
+ ];
20
+ /**
21
+ * Reusable Turndown service instance configured for search snippet and HTML conversion.
22
+ */
23
+ const turndownInstance = new TurndownService({
24
+ headingStyle: "atx",
25
+ codeBlockStyle: "fenced",
26
+ bulletListMarker: "-",
27
+ emDelimiter: "_",
28
+ strongDelimiter: "**",
29
+ });
30
+ turndownInstance.remove([
31
+ "script",
32
+ "style",
33
+ "noscript",
34
+ "svg",
35
+ "iframe",
36
+ "form",
37
+ ]);
38
+ /**
39
+ * Converts HTML snippet markup into clean, readable Markdown text.
40
+ *
41
+ * @param html - Raw HTML snippet string.
42
+ * @returns Clean Markdown string with entities decoded and excessive whitespace collapsed.
43
+ */
44
+ export function convertSnippetToMarkdown(html) {
45
+ if (!html || html.trim().length === 0) {
46
+ return "";
47
+ }
48
+ const cleaned = html
49
+ .replace(/<!--[\s\S]*?-->/g, "")
50
+ .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "")
51
+ .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, "");
52
+ const markdown = turndownInstance.turndown(cleaned);
53
+ return markdown.replace(/\s+/g, " ").trim();
54
+ }
55
+ /**
56
+ * Unwraps DuckDuckGo redirect tracking URLs into clean, canonical target URLs.
57
+ * Handles formats like `//duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com&rut=...`.
58
+ *
59
+ * @param rawUrl - The raw URL string from DuckDuckGo search results.
60
+ * @returns Unwrapped canonical target URL.
61
+ */
62
+ export function unwrapDuckDuckGoUrl(rawUrl) {
63
+ if (!rawUrl) {
64
+ return "";
65
+ }
66
+ const unescaped = rawUrl.replace(/&amp;/g, "&").trim();
67
+ // If already a standard direct URL without DuckDuckGo redirect wrapping
68
+ if (!unescaped.includes("duckduckgo.com/l/") &&
69
+ !unescaped.includes("/l/?uddg=")) {
70
+ if (unescaped.startsWith("//")) {
71
+ return `https:${unescaped}`;
72
+ }
73
+ return unescaped;
74
+ }
75
+ try {
76
+ const fullUrl = unescaped.startsWith("//")
77
+ ? `https:${unescaped}`
78
+ : unescaped.startsWith("/")
79
+ ? `https://duckduckgo.com${unescaped}`
80
+ : unescaped;
81
+ const parsed = new URL(fullUrl);
82
+ const uddgParam = parsed.searchParams.get("uddg");
83
+ if (uddgParam) {
84
+ return decodeURIComponent(uddgParam);
85
+ }
86
+ return fullUrl;
87
+ }
88
+ catch {
89
+ return unescaped;
90
+ }
91
+ }
92
+ /**
93
+ * Extracts the hostname domain from a URL safely.
94
+ *
95
+ * @param targetUrl - Valid URL string.
96
+ * @returns Hostname without leading "www.", or empty string on error.
97
+ */
98
+ export function extractDomainFromUrl(targetUrl) {
99
+ try {
100
+ const parsed = new URL(targetUrl);
101
+ return parsed.hostname.replace(/^www\./, "");
102
+ }
103
+ catch {
104
+ return "";
105
+ }
106
+ }
107
+ /**
108
+ * Selects a random modern user agent string to mimic diverse user traffic.
109
+ *
110
+ * @returns Modern browser User-Agent string.
111
+ */
112
+ function getRandomUserAgent() {
113
+ const index = Math.floor(Math.random() * realisticUserAgents.length);
114
+ return realisticUserAgents[index] ?? realisticUserAgents[0];
115
+ }
116
+ /**
117
+ * Builds realistic browser request headers adhering to modern HTTP standards.
118
+ *
119
+ * @returns Headers dictionary for HTTP requests.
120
+ */
121
+ function buildRealisticBrowserHeaders() {
122
+ return {
123
+ "User-Agent": getRandomUserAgent(),
124
+ Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
125
+ "Accept-Language": "en-US,en;q=0.9",
126
+ "Sec-Fetch-Dest": "document",
127
+ "Sec-Fetch-Mode": "navigate",
128
+ "Sec-Fetch-Site": "none",
129
+ "Sec-Fetch-User": "?1",
130
+ "Upgrade-Insecure-Requests": "1",
131
+ "Cache-Control": "max-age=0",
132
+ };
133
+ }
134
+ /**
135
+ * Maps time filter to DuckDuckGo parameter value.
136
+ *
137
+ * @param time - Semantic time filter.
138
+ * @returns DuckDuckGo df parameter value.
139
+ */
140
+ function mapTimeFilter(time) {
141
+ switch (time) {
142
+ case "day":
143
+ return "d";
144
+ case "week":
145
+ return "w";
146
+ case "month":
147
+ return "m";
148
+ case "year":
149
+ return "y";
150
+ default:
151
+ return "";
152
+ }
153
+ }
154
+ /**
155
+ * Maps SafeSearch level to DuckDuckGo parameter value.
156
+ *
157
+ * @param level - SafeSearch setting.
158
+ * @returns DuckDuckGo kp parameter value.
159
+ */
160
+ function mapSafeSearch(level) {
161
+ switch (level) {
162
+ case "strict":
163
+ return "1";
164
+ case "off":
165
+ return "-2";
166
+ case "moderate":
167
+ default:
168
+ return "-1";
169
+ }
170
+ }
171
+ /**
172
+ * Introduces human-like random jitter delay (100ms - 300ms) to prevent burst patterns.
173
+ *
174
+ * @param abortSignal - Optional signal to abort wait.
175
+ */
176
+ async function applyHumanJitter(abortSignal) {
177
+ const delayMs = Math.floor(100 + Math.random() * 200);
178
+ await new Promise((resolve, reject) => {
179
+ if (abortSignal?.aborted) {
180
+ reject(abortSignal.reason);
181
+ return;
182
+ }
183
+ const timer = setTimeout(() => {
184
+ resolve();
185
+ }, delayMs);
186
+ abortSignal?.addEventListener("abort", () => {
187
+ clearTimeout(timer);
188
+ reject(abortSignal.reason);
189
+ }, { once: true });
190
+ });
191
+ }
192
+ /**
193
+ * Checks whether a given target domain passes allowed and blocked domain filters.
194
+ *
195
+ * @param domain - Domain extracted from result URL.
196
+ * @param allowedDomains - Optional list of permitted domains.
197
+ * @param blockedDomains - Optional list of forbidden domains.
198
+ * @returns True if the domain passes all filters, false otherwise.
199
+ */
200
+ export function isDomainAllowed(domain, allowedDomains, blockedDomains) {
201
+ const lowerDomain = domain.toLowerCase();
202
+ if (blockedDomains && blockedDomains.length > 0) {
203
+ const isBlocked = blockedDomains.some((blocked) => {
204
+ const lowerBlocked = blocked.toLowerCase().replace(/^www\./, "");
205
+ return (lowerDomain === lowerBlocked || lowerDomain.endsWith(`.${lowerBlocked}`));
206
+ });
207
+ if (isBlocked) {
208
+ return false;
209
+ }
210
+ }
211
+ if (allowedDomains && allowedDomains.length > 0) {
212
+ return allowedDomains.some((allowed) => {
213
+ const lowerAllowed = allowed.toLowerCase().replace(/^www\./, "");
214
+ return (lowerDomain === lowerAllowed || lowerDomain.endsWith(`.${lowerAllowed}`));
215
+ });
216
+ }
217
+ return true;
218
+ }
219
+ /**
220
+ * Fetches instant answers from DuckDuckGo Instant Answer API.
221
+ *
222
+ * @param query - Search query.
223
+ * @param fetchFn - Fetch implementation.
224
+ * @param abortSignal - Optional abort signal.
225
+ * @returns Instant answer metadata if found, or undefined.
226
+ */
227
+ export async function fetchDuckDuckGoInstantAnswer(query, fetchFn, abortSignal) {
228
+ try {
229
+ const apiUrl = new URL("https://api.duckduckgo.com/");
230
+ apiUrl.searchParams.set("q", query);
231
+ apiUrl.searchParams.set("format", "json");
232
+ apiUrl.searchParams.set("no_html", "1");
233
+ apiUrl.searchParams.set("no_redirect", "1");
234
+ const response = await fetchFn(apiUrl.toString(), {
235
+ method: "GET",
236
+ headers: {
237
+ "User-Agent": getRandomUserAgent(),
238
+ Accept: "application/json",
239
+ },
240
+ ...(abortSignal ? { signal: abortSignal } : {}),
241
+ });
242
+ if (!response.ok) {
243
+ return undefined;
244
+ }
245
+ const data = (await response.json());
246
+ if (!data.Abstract &&
247
+ (!data.RelatedTopics || data.RelatedTopics.length === 0)) {
248
+ return undefined;
249
+ }
250
+ const relatedTopics = data.RelatedTopics?.filter((t) => typeof t.Text === "string" && typeof t.FirstURL === "string").map((topic) => ({
251
+ text: topic.Text,
252
+ url: topic.FirstURL,
253
+ })) ?? [];
254
+ return {
255
+ ...(data.Heading ? { heading: data.Heading } : {}),
256
+ ...(data.Abstract ? { abstract: data.Abstract } : {}),
257
+ ...(data.AbstractSource ? { source: data.AbstractSource } : {}),
258
+ ...(data.AbstractURL ? { sourceUrl: data.AbstractURL } : {}),
259
+ ...(relatedTopics.length > 0 ? { relatedTopics } : {}),
260
+ };
261
+ }
262
+ catch {
263
+ return undefined;
264
+ }
265
+ }
266
+ /**
267
+ * Parses organic search results from html.duckduckgo.com HTML string.
268
+ *
269
+ * @param html - Raw HTML from html.duckduckgo.com.
270
+ * @returns Parsed items and next page metadata.
271
+ */
272
+ function parseHtmlResults(html) {
273
+ const items = [];
274
+ // Match organic web results: exclude ad containers (class="result--ad")
275
+ const resultRegex = /<div class="result results_links results_links_deep web-result[\s\S]*?<h2 class="result__title">[\s\S]*?<a rel="nofollow" class="result__a" href="([^"]+)">([\s\S]*?)<\/a>[\s\S]*?<a class="result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/g;
276
+ const matches = [...html.matchAll(resultRegex)];
277
+ for (const match of matches) {
278
+ const rawUrl = match[1] ?? "";
279
+ const rawTitle = match[2] ?? "";
280
+ const rawSnippet = match[3] ?? "";
281
+ // Skip ad redirect endpoints
282
+ if (rawUrl.includes("duckduckgo.com/y.js")) {
283
+ continue;
284
+ }
285
+ const unwrappedUrl = unwrapDuckDuckGoUrl(rawUrl);
286
+ if (!unwrappedUrl || unwrappedUrl.startsWith("/")) {
287
+ continue;
288
+ }
289
+ const domain = extractDomainFromUrl(unwrappedUrl);
290
+ const title = convertSnippetToMarkdown(rawTitle);
291
+ const snippet = convertSnippetToMarkdown(rawSnippet);
292
+ items.push({
293
+ title,
294
+ url: unwrappedUrl,
295
+ domain,
296
+ snippet,
297
+ });
298
+ }
299
+ // Extract pagination and session tokens from next page form
300
+ let nextOffset;
301
+ let vqd;
302
+ const allForms = [...html.matchAll(/<form[\s\S]*?<\/form>/g)];
303
+ for (const formMatch of allForms) {
304
+ const formHtml = formMatch[0];
305
+ const sMatch = formHtml.match(/name="s" value="(\d+)"/);
306
+ if (sMatch?.[1]) {
307
+ nextOffset = parseInt(sMatch[1], 10);
308
+ const vqdMatch = formHtml.match(/name="vqd" value="([^"]+)"/);
309
+ if (vqdMatch?.[1]) {
310
+ vqd = vqdMatch[1];
311
+ }
312
+ break;
313
+ }
314
+ }
315
+ return { items, nextOffset, vqd };
316
+ }
317
+ /**
318
+ * Parses organic search results from lite.duckduckgo.com HTML string (fallback).
319
+ *
320
+ * @param html - Raw HTML from lite.duckduckgo.com.
321
+ * @returns Parsed items and next page metadata.
322
+ */
323
+ function parseLiteResults(html) {
324
+ const items = [];
325
+ // Match result links and corresponding snippets in lite tables
326
+ const rows = [...html.matchAll(/<tr>[\s\S]*?<\/tr>/g)];
327
+ for (let i = 0; i < rows.length; i++) {
328
+ const row = rows[i]?.[0] ?? "";
329
+ if (row.includes("result-sponsored")) {
330
+ continue;
331
+ }
332
+ const linkMatch = row.match(/<a rel="nofollow" href="([^"]+)" class='result-link'>([\s\S]*?)<\/a>/);
333
+ if (!linkMatch) {
334
+ continue;
335
+ }
336
+ const rawUrl = linkMatch[1] ?? "";
337
+ const rawTitle = linkMatch[2] ?? "";
338
+ if (rawUrl.includes("duckduckgo.com/y.js")) {
339
+ continue;
340
+ }
341
+ const unwrappedUrl = unwrapDuckDuckGoUrl(rawUrl);
342
+ if (!unwrappedUrl || unwrappedUrl.startsWith("/")) {
343
+ continue;
344
+ }
345
+ // Look for snippet in subsequent row
346
+ let snippet = "";
347
+ if (i + 1 < rows.length) {
348
+ const nextRow = rows[i + 1]?.[0] ?? "";
349
+ const snippetMatch = nextRow.match(/<td class='result-snippet'>([\s\S]*?)<\/td>/);
350
+ if (snippetMatch?.[1]) {
351
+ snippet = convertSnippetToMarkdown(snippetMatch[1]);
352
+ }
353
+ }
354
+ const domain = extractDomainFromUrl(unwrappedUrl);
355
+ const title = convertSnippetToMarkdown(rawTitle);
356
+ items.push({
357
+ title,
358
+ url: unwrappedUrl,
359
+ domain,
360
+ snippet,
361
+ });
362
+ }
363
+ let nextOffset;
364
+ const allLiteForms = [...html.matchAll(/<form[\s\S]*?<\/form>/g)];
365
+ for (const formMatch of allLiteForms) {
366
+ const formHtml = formMatch[0];
367
+ const sMatch = formHtml.match(/name="s" value="(\d+)"/);
368
+ if (sMatch?.[1]) {
369
+ nextOffset = parseInt(sMatch[1], 10);
370
+ break;
371
+ }
372
+ }
373
+ return { items, nextOffset };
374
+ }
375
+ /**
376
+ * Formats structured search results and instant answers into clean Markdown.
377
+ *
378
+ * @param query - Original search query.
379
+ * @param results - Array of organic search results.
380
+ * @param instant - Optional instant answer metadata.
381
+ * @param offset - Current page offset.
382
+ * @returns Clean, structured Markdown representation.
383
+ */
384
+ export function formatSearchResultsToMarkdown(query, results, instant, offset = 0) {
385
+ const lines = [];
386
+ lines.push(`## Search Results for "${query}"`);
387
+ if (instant?.abstract) {
388
+ lines.push(`\n### Instant Answer: ${instant.heading ?? query}`);
389
+ lines.push(instant.abstract);
390
+ if (instant.sourceUrl) {
391
+ lines.push(`_Source: [${instant.source ?? "Source"}](${instant.sourceUrl})_`);
392
+ }
393
+ lines.push("");
394
+ }
395
+ if (results.length === 0) {
396
+ lines.push("\n_No matching results found._");
397
+ return lines.join("\n");
398
+ }
399
+ lines.push(`\n**Found ${results.length} results (Page offset: ${offset}):**\n`);
400
+ for (let i = 0; i < results.length; i++) {
401
+ const item = results[i];
402
+ const rank = offset + i + 1;
403
+ lines.push(`### ${rank}. [${item.title}](${item.url})`);
404
+ lines.push(`**Domain:** \`${item.domain}\``);
405
+ if (item.snippet) {
406
+ lines.push(`> ${item.snippet}`);
407
+ }
408
+ lines.push("");
409
+ }
410
+ return lines.join("\n").trim();
411
+ }
412
+ /**
413
+ * Executes a DuckDuckGo search query using primary GET html.duckduckgo.com with automatic
414
+ * failover to lite.duckduckgo.com, URL unwrapping, filtering, and Markdown formatting.
415
+ *
416
+ * @param options - Configured search options.
417
+ * @returns Complete structured search result including formatted Markdown.
418
+ */
419
+ export async function executeDuckDuckGoSearch(options) {
420
+ const query = options.query.trim();
421
+ if (!query) {
422
+ throw new Error("Search query cannot be empty.");
423
+ }
424
+ const limit = Math.max(1, Math.min(options.limit ?? 10, 25));
425
+ const offset = Math.max(0, options.offset ?? 0);
426
+ const fetchFn = options.customFetch ?? globalThis.fetch;
427
+ if (options.enableJitter !== false) {
428
+ await applyHumanJitter(options.abortSignal);
429
+ }
430
+ // Concurrently fetch instant answer if on first page
431
+ let instantPromise = Promise.resolve(undefined);
432
+ if (offset === 0) {
433
+ instantPromise = fetchDuckDuckGoInstantAnswer(query, fetchFn, options.abortSignal);
434
+ }
435
+ // Construct GET URL for html.duckduckgo.com
436
+ const primaryUrl = new URL("https://html.duckduckgo.com/html/");
437
+ primaryUrl.searchParams.set("q", query);
438
+ if (offset > 0) {
439
+ primaryUrl.searchParams.set("s", offset.toString());
440
+ }
441
+ const df = mapTimeFilter(options.time);
442
+ if (df) {
443
+ primaryUrl.searchParams.set("df", df);
444
+ }
445
+ const kp = mapSafeSearch(options.safeSearch);
446
+ primaryUrl.searchParams.set("kp", kp);
447
+ if (options.region) {
448
+ primaryUrl.searchParams.set("kl", options.region);
449
+ }
450
+ let items = [];
451
+ let nextOffset;
452
+ let vqd;
453
+ let primarySucceeded = false;
454
+ try {
455
+ const response = await fetchFn(primaryUrl.toString(), {
456
+ method: "GET",
457
+ headers: buildRealisticBrowserHeaders(),
458
+ ...(options.abortSignal ? { signal: options.abortSignal } : {}),
459
+ });
460
+ if (response.ok) {
461
+ const html = await response.text();
462
+ // Ensure response is not an anomaly/bot block
463
+ if (!html.includes("anomaly-modal") &&
464
+ !html.includes("anomalyDetectionBlock")) {
465
+ const parsed = parseHtmlResults(html);
466
+ if (parsed.items.length > 0) {
467
+ items = parsed.items;
468
+ nextOffset = parsed.nextOffset;
469
+ vqd = parsed.vqd;
470
+ primarySucceeded = true;
471
+ }
472
+ }
473
+ }
474
+ }
475
+ catch {
476
+ primarySucceeded = false;
477
+ }
478
+ // Automatic fallback to lite.duckduckgo.com if primary failed or yielded 0 items
479
+ if (!primarySucceeded) {
480
+ try {
481
+ const liteBody = new URLSearchParams();
482
+ liteBody.set("q", query);
483
+ if (offset > 0) {
484
+ liteBody.set("s", offset.toString());
485
+ }
486
+ if (df) {
487
+ liteBody.set("df", df);
488
+ }
489
+ if (options.region) {
490
+ liteBody.set("kl", options.region);
491
+ }
492
+ const liteResponse = await fetchFn("https://lite.duckduckgo.com/lite/", {
493
+ method: "POST",
494
+ headers: {
495
+ ...buildRealisticBrowserHeaders(),
496
+ "Content-Type": "application/x-www-form-urlencoded",
497
+ },
498
+ body: liteBody.toString(),
499
+ ...(options.abortSignal ? { signal: options.abortSignal } : {}),
500
+ });
501
+ if (liteResponse.ok) {
502
+ const liteHtml = await liteResponse.text();
503
+ const parsed = parseLiteResults(liteHtml);
504
+ items = parsed.items;
505
+ nextOffset = parsed.nextOffset;
506
+ }
507
+ }
508
+ catch (err) {
509
+ if (items.length === 0) {
510
+ throw new Error(`DuckDuckGo search failed: ${err instanceof Error ? err.message : String(err)}`);
511
+ }
512
+ }
513
+ }
514
+ // Filter by allowed / blocked domains if specified
515
+ if ((options.allowedDomains && options.allowedDomains.length > 0) ||
516
+ (options.blockedDomains && options.blockedDomains.length > 0)) {
517
+ items = items.filter((item) => isDomainAllowed(item.domain, options.allowedDomains, options.blockedDomains));
518
+ }
519
+ // Truncate to desired limit
520
+ const finalResults = items.slice(0, limit);
521
+ const instantAnswer = await instantPromise;
522
+ const markdown = formatSearchResultsToMarkdown(query, finalResults, instantAnswer, offset);
523
+ return {
524
+ query,
525
+ results: finalResults,
526
+ totalResults: finalResults.length,
527
+ offset,
528
+ ...(nextOffset !== undefined ? { nextOffset } : {}),
529
+ hasNextPage: nextOffset !== undefined,
530
+ ...(vqd ? { vqd } : {}),
531
+ ...(instantAnswer ? { instantAnswer } : {}),
532
+ markdown,
533
+ };
534
+ }
535
+ //# sourceMappingURL=duckDuckGo.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"duckDuckGo.js","sources":["../../../src/tools/internal/duckDuckGo.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @fileoverview SSRF (Server-Side Request Forgery) protection and URL validation utilities.
3
+ * Ensures the WebFetch tool only reaches public, safe internet endpoints and rejects
4
+ * private, loopback, cloud metadata, and link-local addresses using `ipaddr.js`.
5
+ * @packageDocumentation
6
+ */
7
+ /**
8
+ * Maximum permitted URL character length to prevent buffer and memory abuse.
9
+ */
10
+ export declare const maxUrlLength = 2048;
11
+ /**
12
+ * Evaluates whether a given hostname is a private, loopback, or internal address.
13
+ *
14
+ * @param hostname - The target hostname or IP string.
15
+ * @returns True if the host is private, loopback, or internal.
16
+ */
17
+ export declare function isPrivateOrBlockedHost(hostname: string): boolean;
18
+ /**
19
+ * Validates and normalizes an input URL for web fetching.
20
+ *
21
+ * @param rawUrl - The raw URL string provided by the caller or model.
22
+ * @returns A parsed and validated URL object.
23
+ * @throws Error if the URL is invalid, too long, uses credentials, or targets private IPs.
24
+ */
25
+ export declare function validateWebUrl(rawUrl: string): URL;
26
+ /**
27
+ * Evaluates whether a redirect from originalUrl to redirectUrl is permitted to be
28
+ * followed automatically without returning a cross-host halt.
29
+ *
30
+ * Same-host redirects (and www <-> non-www variations) on the same protocol and port
31
+ * are permitted. Cross-host redirects are rejected to preserve agent oversight.
32
+ *
33
+ * @param originalUrl - The starting URL string.
34
+ * @param redirectUrl - The target location URL string.
35
+ * @returns True if the redirect stays within the permitted same-domain scope.
36
+ */
37
+ export declare function isPermittedRedirect(originalUrl: string, redirectUrl: string): boolean;
38
+ //# sourceMappingURL=ssrfGuard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ssrfGuard.d.ts","sources":["../../../src/tools/internal/ssrfGuard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AA4CjC;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CA2BhE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAqClD;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAyBT"}