@amaranthic/hernex 0.4.0 → 0.5.1
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.
- package/CHANGELOG.md +57 -0
- package/dist/engine/runTurn.d.ts.map +1 -1
- package/dist/engine/runTurn.js +3 -0
- package/dist/engine/runTurn.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/tools/ToolExecutionContext.d.ts +13 -0
- package/dist/tools/ToolExecutionContext.d.ts.map +1 -1
- package/dist/tools/ToolRegistry.d.ts +3 -3
- package/dist/tools/ToolRegistry.d.ts.map +1 -1
- package/dist/tools/ToolRegistry.js +5 -1
- package/dist/tools/ToolRegistry.js.map +1 -1
- package/dist/tools/WebFetchTool.d.ts +126 -0
- package/dist/tools/WebFetchTool.d.ts.map +1 -0
- package/dist/tools/WebFetchTool.js +374 -0
- package/dist/tools/WebFetchTool.js.map +1 -0
- package/dist/tools/WebSearchTool.d.ts +181 -0
- package/dist/tools/WebSearchTool.d.ts.map +1 -0
- package/dist/tools/WebSearchTool.js +207 -0
- package/dist/tools/WebSearchTool.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +3 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/internal/duckDuckGo.d.ts +217 -0
- package/dist/tools/internal/duckDuckGo.d.ts.map +1 -0
- package/dist/tools/internal/duckDuckGo.js +535 -0
- package/dist/tools/internal/duckDuckGo.js.map +1 -0
- package/dist/tools/internal/ssrfGuard.d.ts +38 -0
- package/dist/tools/internal/ssrfGuard.d.ts.map +1 -0
- package/dist/tools/internal/ssrfGuard.js +155 -0
- package/dist/tools/internal/ssrfGuard.js.map +1 -0
- package/dist/tools/prompts.d.ts +8 -0
- package/dist/tools/prompts.d.ts.map +1 -1
- package/dist/tools/prompts.js +14 -0
- package/dist/tools/prompts.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,207 @@
|
|
|
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 { executeDuckDuckGoSearch, } from "./internal/duckDuckGo.js";
|
|
9
|
+
import { webSearchDescription } from "./prompts.js";
|
|
10
|
+
/**
|
|
11
|
+
* Default cache time-to-live in milliseconds (15 minutes).
|
|
12
|
+
*/
|
|
13
|
+
const defaultCacheTtlMs = 15 * 60 * 1000;
|
|
14
|
+
/**
|
|
15
|
+
* Zod schema defining valid input parameters for WebSearchTool.
|
|
16
|
+
*/
|
|
17
|
+
export const webSearchInputSchema = z.object({
|
|
18
|
+
query: z
|
|
19
|
+
.string()
|
|
20
|
+
.min(1, "Search query cannot be empty.")
|
|
21
|
+
.describe("The search query terms to find on the web."),
|
|
22
|
+
limit: z
|
|
23
|
+
.number()
|
|
24
|
+
.int()
|
|
25
|
+
.min(1)
|
|
26
|
+
.max(25)
|
|
27
|
+
.default(10)
|
|
28
|
+
.optional()
|
|
29
|
+
.describe("Maximum number of search results to return (1-25, default: 10)."),
|
|
30
|
+
offset: z
|
|
31
|
+
.number()
|
|
32
|
+
.int()
|
|
33
|
+
.min(0)
|
|
34
|
+
.default(0)
|
|
35
|
+
.optional()
|
|
36
|
+
.describe("Pagination offset index for results (e.g. 0 for first page, 10 for second page)."),
|
|
37
|
+
time: z
|
|
38
|
+
.enum(["all", "day", "week", "month", "year"])
|
|
39
|
+
.optional()
|
|
40
|
+
.describe("Time range filter for results: 'day' (past 24h), 'week' (past 7 days), 'month', 'year', or 'all'."),
|
|
41
|
+
safeSearch: z
|
|
42
|
+
.enum(["strict", "moderate", "off"])
|
|
43
|
+
.optional()
|
|
44
|
+
.describe("SafeSearch moderation filter level: 'strict', 'moderate' (default), or 'off'."),
|
|
45
|
+
region: z
|
|
46
|
+
.string()
|
|
47
|
+
.optional()
|
|
48
|
+
.describe("Geographic region / country code for search results (e.g. 'us-en', 'uk-en', 'in-en', 'wt-wt')."),
|
|
49
|
+
allowedDomains: z
|
|
50
|
+
.array(z.string())
|
|
51
|
+
.optional()
|
|
52
|
+
.describe("Optional whitelist of domain names to restrict results to (e.g. ['github.com', 'wikipedia.org'])."),
|
|
53
|
+
blockedDomains: z
|
|
54
|
+
.array(z.string())
|
|
55
|
+
.optional()
|
|
56
|
+
.describe("Optional blacklist of domain names to exclude from results."),
|
|
57
|
+
});
|
|
58
|
+
/**
|
|
59
|
+
* Built-in agent tool for searching the web via DuckDuckGo with automatic URL unwrapping,
|
|
60
|
+
* HTML-to-Markdown conversion via Turndown, pagination, filtering, and caching.
|
|
61
|
+
*/
|
|
62
|
+
export class WebSearchTool {
|
|
63
|
+
/**
|
|
64
|
+
* Unique name of the tool in the agent registry.
|
|
65
|
+
*/
|
|
66
|
+
name = "webSearch";
|
|
67
|
+
/**
|
|
68
|
+
* Detailed system instruction prompt describing the tool.
|
|
69
|
+
*/
|
|
70
|
+
description = webSearchDescription;
|
|
71
|
+
/**
|
|
72
|
+
* Zod input schema for parameter validation.
|
|
73
|
+
*/
|
|
74
|
+
inputSchema = webSearchInputSchema;
|
|
75
|
+
/**
|
|
76
|
+
* In-memory cache time-to-live in milliseconds.
|
|
77
|
+
*/
|
|
78
|
+
cacheTtlMs;
|
|
79
|
+
/**
|
|
80
|
+
* Custom fetch function override.
|
|
81
|
+
*/
|
|
82
|
+
fetchFn;
|
|
83
|
+
/**
|
|
84
|
+
* Whether human-like timing jitter is enabled.
|
|
85
|
+
*/
|
|
86
|
+
enableJitter;
|
|
87
|
+
/**
|
|
88
|
+
* In-memory response cache mapped by normalized query key.
|
|
89
|
+
*/
|
|
90
|
+
cache = new Map();
|
|
91
|
+
/**
|
|
92
|
+
* Creates a new WebSearchTool instance with optional caching and fetch overrides.
|
|
93
|
+
*
|
|
94
|
+
* @param options - Configuration options for the search tool.
|
|
95
|
+
*/
|
|
96
|
+
constructor(options) {
|
|
97
|
+
this.cacheTtlMs = options?.cacheTtlMs ?? defaultCacheTtlMs;
|
|
98
|
+
this.fetchFn = options?.customFetch;
|
|
99
|
+
this.enableJitter = options?.enableJitter ?? true;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Generates a stable deterministic cache key from input parameters.
|
|
103
|
+
*
|
|
104
|
+
* @param parameters - Search input parameters.
|
|
105
|
+
* @returns Deterministic cache key string.
|
|
106
|
+
*/
|
|
107
|
+
getCacheKey(parameters) {
|
|
108
|
+
return JSON.stringify({
|
|
109
|
+
q: parameters.query.trim().toLowerCase(),
|
|
110
|
+
limit: parameters.limit ?? 10,
|
|
111
|
+
offset: parameters.offset ?? 0,
|
|
112
|
+
time: parameters.time,
|
|
113
|
+
safeSearch: parameters.safeSearch,
|
|
114
|
+
region: parameters.region,
|
|
115
|
+
allowedDomains: parameters.allowedDomains
|
|
116
|
+
? [...parameters.allowedDomains].sort()
|
|
117
|
+
: undefined,
|
|
118
|
+
blockedDomains: parameters.blockedDomains
|
|
119
|
+
? [...parameters.blockedDomains].sort()
|
|
120
|
+
: undefined,
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Executes the web search operation, respecting in-memory caching and fail-soft semantics.
|
|
125
|
+
*
|
|
126
|
+
* @param parameters - Validated search parameters.
|
|
127
|
+
* @param context - The execution context with abortSignal and credentials.
|
|
128
|
+
* @returns A promise resolving to the structured search output.
|
|
129
|
+
*/
|
|
130
|
+
async execute(parameters, context) {
|
|
131
|
+
const startTime = Date.now();
|
|
132
|
+
const cacheKey = this.getCacheKey(parameters);
|
|
133
|
+
const existing = this.cache.get(cacheKey);
|
|
134
|
+
if (existing && Date.now() - existing.timestamp < this.cacheTtlMs) {
|
|
135
|
+
return {
|
|
136
|
+
...existing.output,
|
|
137
|
+
cached: true,
|
|
138
|
+
durationMs: Date.now() - startTime,
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
try {
|
|
142
|
+
const searchResult = await executeDuckDuckGoSearch({
|
|
143
|
+
query: parameters.query,
|
|
144
|
+
limit: parameters.limit,
|
|
145
|
+
offset: parameters.offset,
|
|
146
|
+
time: parameters.time,
|
|
147
|
+
safeSearch: parameters.safeSearch,
|
|
148
|
+
region: parameters.region,
|
|
149
|
+
allowedDomains: parameters.allowedDomains,
|
|
150
|
+
blockedDomains: parameters.blockedDomains,
|
|
151
|
+
abortSignal: context.abortSignal,
|
|
152
|
+
customFetch: this.fetchFn,
|
|
153
|
+
enableJitter: this.enableJitter,
|
|
154
|
+
});
|
|
155
|
+
const outputData = {
|
|
156
|
+
query: searchResult.query,
|
|
157
|
+
results: searchResult.results,
|
|
158
|
+
totalResults: searchResult.totalResults,
|
|
159
|
+
offset: searchResult.offset,
|
|
160
|
+
...(searchResult.nextOffset !== undefined
|
|
161
|
+
? { nextOffset: searchResult.nextOffset }
|
|
162
|
+
: {}),
|
|
163
|
+
hasNextPage: searchResult.hasNextPage,
|
|
164
|
+
...(searchResult.instantAnswer
|
|
165
|
+
? { instantAnswer: searchResult.instantAnswer }
|
|
166
|
+
: {}),
|
|
167
|
+
content: searchResult.markdown,
|
|
168
|
+
};
|
|
169
|
+
this.cache.set(cacheKey, {
|
|
170
|
+
output: outputData,
|
|
171
|
+
timestamp: Date.now(),
|
|
172
|
+
});
|
|
173
|
+
return {
|
|
174
|
+
...outputData,
|
|
175
|
+
cached: false,
|
|
176
|
+
durationMs: Date.now() - startTime,
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
catch (error) {
|
|
180
|
+
// Return structured fail-soft response rather than unhandled exception
|
|
181
|
+
const errorMessage = error instanceof Error ? error.message : String(error);
|
|
182
|
+
const failSoftContent = `## Web Search Error\n\n` +
|
|
183
|
+
`Failed to retrieve search results for "${parameters.query}": ${errorMessage}\n\n` +
|
|
184
|
+
`_Suggestion: You may try rewording the query, removing restrictive filters, or using webFetch if you have a specific URL._`;
|
|
185
|
+
return {
|
|
186
|
+
query: parameters.query,
|
|
187
|
+
results: [],
|
|
188
|
+
totalResults: 0,
|
|
189
|
+
offset: parameters.offset ?? 0,
|
|
190
|
+
hasNextPage: false,
|
|
191
|
+
cached: false,
|
|
192
|
+
durationMs: Date.now() - startTime,
|
|
193
|
+
content: failSoftContent,
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Factory helper function to create a configured WebSearchTool instance.
|
|
200
|
+
*
|
|
201
|
+
* @param options - Optional configuration options for the search tool.
|
|
202
|
+
* @returns An initialized WebSearchTool instance.
|
|
203
|
+
*/
|
|
204
|
+
export function createWebSearchTool(options) {
|
|
205
|
+
return new WebSearchTool(options);
|
|
206
|
+
}
|
|
207
|
+
//# sourceMappingURL=WebSearchTool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"WebSearchTool.js","sources":["../../src/tools/WebSearchTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,uBAAuB,GAKxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;GAEG;AACH,MAAM,iBAAiB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,+BAA+B,CAAC;SACvC,QAAQ,CAAC,4CAA4C,CAAC;IACzD,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,EAAE;SACV,QAAQ,CACP,iEAAiE,CAClE;IACH,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,CAAC,CAAC;SACV,QAAQ,EAAE;SACV,QAAQ,CACP,kFAAkF,CACnF;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;SAC7C,QAAQ,EAAE;SACV,QAAQ,CACP,mGAAmG,CACpG;IACH,UAAU,EAAE,CAAC;SACV,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;SACnC,QAAQ,EAAE;SACV,QAAQ,CACP,+EAA+E,CAChF;IACH,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,gGAAgG,CACjG;IACH,cAAc,EAAE,CAAC;SACd,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CACP,mGAAmG,CACpG;IACH,cAAc,EAAE,CAAC;SACd,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,6DAA6D,CAAC;CAC3E,CAAC,CAAC;AA0FH;;;GAGG;AACH,MAAM,OAAO,aAAa;IAIxB;;OAEG;IACa,IAAI,GAAG,WAAW,CAAC;IAEnC;;OAEG;IACa,WAAW,GAAG,oBAAoB,CAAC;IAEnD;;OAEG;IACa,WAAW,GAAG,oBAAoB,CAAC;IAEnD;;OAEG;IACc,UAAU,CAAS;IAEpC;;OAEG;IACc,OAAO,CAA4B;IAEpD;;OAEG;IACc,YAAY,CAAU;IAEvC;;OAEG;IACc,KAAK,GAAG,IAAI,GAAG,EAA8B,CAAC;IAE/D;;;;OAIG;IACH,YAAmB,OAA8B;QAC/C,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,iBAAiB,CAAC;QAC3D,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,WAAW,CAAC;QACpC,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,IAAI,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACK,WAAW,CAAC,UAA0B;QAC5C,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;YACxC,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,EAAE;YAC7B,MAAM,EAAE,UAAU,CAAC,MAAM,IAAI,CAAC;YAC9B,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,cAAc,EAAE,UAAU,CAAC,cAAc;gBACvC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE;gBACvC,CAAC,CAAC,SAAS;YACb,cAAc,EAAE,UAAU,CAAC,cAAc;gBACvC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE;gBACvC,CAAC,CAAC,SAAS;SACd,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAO,CAClB,UAA0B,EAC1B,OAA6B;QAE7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAClE,OAAO;gBACL,GAAG,QAAQ,CAAC,MAAM;gBAClB,MAAM,EAAE,IAAI;gBACZ,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACnC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,uBAAuB,CAAC;gBACjD,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,IAAI,EAAE,UAAU,CAAC,IAAoC;gBACrD,UAAU,EAAE,UAAU,CAAC,UAAyC;gBAChE,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,cAAc,EAAE,UAAU,CAAC,cAAc;gBACzC,cAAc,EAAE,UAAU,CAAC,cAAc;gBACzC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,WAAW,EAAE,IAAI,CAAC,OAAO;gBACzB,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC,CAAC,CAAC;YAEH,MAAM,UAAU,GAAmD;gBACjE,KAAK,EAAE,YAAY,CAAC,KAAK;gBACzB,OAAO,EAAE,YAAY,CAAC,OAAO;gBAC7B,YAAY,EAAE,YAAY,CAAC,YAAY;gBACvC,MAAM,EAAE,YAAY,CAAC,MAAM;gBAC3B,GAAG,CAAC,YAAY,CAAC,UAAU,KAAK,SAAS;oBACvC,CAAC,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,UAAU,EAAE;oBACzC,CAAC,CAAC,EAAE,CAAC;gBACP,WAAW,EAAE,YAAY,CAAC,WAAW;gBACrC,GAAG,CAAC,YAAY,CAAC,aAAa;oBAC5B,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,CAAC,aAAa,EAAE;oBAC/C,CAAC,CAAC,EAAE,CAAC;gBACP,OAAO,EAAE,YAAY,CAAC,QAAQ;aAC/B,CAAC;YAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE;gBACvB,MAAM,EAAE,UAAU;gBAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAC;YAEH,OAAO;gBACL,GAAG,UAAU;gBACb,MAAM,EAAE,KAAK;gBACb,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACnC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,uEAAuE;YACvE,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,MAAM,eAAe,GACnB,yBAAyB;gBACzB,0CAA0C,UAAU,CAAC,KAAK,MAAM,YAAY,MAAM;gBAClF,4HAA4H,CAAC;YAE/H,OAAO;gBACL,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,OAAO,EAAE,EAAE;gBACX,YAAY,EAAE,CAAC;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM,IAAI,CAAC;gBAC9B,WAAW,EAAE,KAAK;gBAClB,MAAM,EAAE,KAAK;gBACb,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBAClC,OAAO,EAAE,eAAe;aACzB,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA8B;IAE9B,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC"}
|
package/dist/tools/index.d.ts
CHANGED
|
@@ -14,4 +14,7 @@ export * from "./TaskManagerTool.js";
|
|
|
14
14
|
export * from "../tasks/index.js";
|
|
15
15
|
export * from "./GlobTool.js";
|
|
16
16
|
export * from "./GrepTool.js";
|
|
17
|
+
export * from "./WebFetchTool.js";
|
|
18
|
+
export * from "./WebSearchTool.js";
|
|
19
|
+
export { type DuckDuckGoSearchResultItem, type DuckDuckGoInstantAnswer, type DuckDuckGoSearchResult, type SearchTimeFilter, type SafeSearchLevel, unwrapDuckDuckGoUrl, convertSnippetToMarkdown, } from "./internal/duckDuckGo.js";
|
|
17
20
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC"}
|
package/dist/tools/index.js
CHANGED
|
@@ -14,4 +14,7 @@ export * from "./TaskManagerTool.js";
|
|
|
14
14
|
export * from "../tasks/index.js";
|
|
15
15
|
export * from "./GlobTool.js";
|
|
16
16
|
export * from "./GrepTool.js";
|
|
17
|
+
export * from "./WebFetchTool.js";
|
|
18
|
+
export * from "./WebSearchTool.js";
|
|
19
|
+
export { unwrapDuckDuckGoUrl, convertSnippetToMarkdown, } from "./internal/duckDuckGo.js";
|
|
17
20
|
//# sourceMappingURL=index.js.map
|
package/dist/tools/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAML,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC"}
|
|
@@ -0,0 +1,217 @@
|
|
|
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
|
+
/**
|
|
9
|
+
* Supported time range filters for search results.
|
|
10
|
+
*/
|
|
11
|
+
export type SearchTimeFilter = "all" | "day" | "week" | "month" | "year";
|
|
12
|
+
/**
|
|
13
|
+
* Supported SafeSearch moderation levels.
|
|
14
|
+
*/
|
|
15
|
+
export type SafeSearchLevel = "strict" | "moderate" | "off";
|
|
16
|
+
/**
|
|
17
|
+
* Search mode category.
|
|
18
|
+
*/
|
|
19
|
+
export type SearchMode = "web" | "instant";
|
|
20
|
+
/**
|
|
21
|
+
* Configuration options for executing a search query.
|
|
22
|
+
*/
|
|
23
|
+
export interface DuckDuckGoSearchOptions {
|
|
24
|
+
/**
|
|
25
|
+
* Search query text.
|
|
26
|
+
*/
|
|
27
|
+
readonly query: string;
|
|
28
|
+
/**
|
|
29
|
+
* Maximum number of organic search results to return (1-25, default: 10).
|
|
30
|
+
*/
|
|
31
|
+
readonly limit?: number | undefined;
|
|
32
|
+
/**
|
|
33
|
+
* Pagination offset index (e.g. 0 for page 1, 10 for page 2).
|
|
34
|
+
*/
|
|
35
|
+
readonly offset?: number | undefined;
|
|
36
|
+
/**
|
|
37
|
+
* Time range filter for results.
|
|
38
|
+
*/
|
|
39
|
+
readonly time?: SearchTimeFilter | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* SafeSearch moderation level.
|
|
42
|
+
*/
|
|
43
|
+
readonly safeSearch?: SafeSearchLevel | undefined;
|
|
44
|
+
/**
|
|
45
|
+
* Geographic region / language code (e.g. "us-en", "uk-en", "wt-wt").
|
|
46
|
+
*/
|
|
47
|
+
readonly region?: string | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* Optional domain whitelist filter (e.g. ["github.com", "typescriptlang.org"]).
|
|
50
|
+
*/
|
|
51
|
+
readonly allowedDomains?: readonly string[] | undefined;
|
|
52
|
+
/**
|
|
53
|
+
* Optional domain blacklist filter.
|
|
54
|
+
*/
|
|
55
|
+
readonly blockedDomains?: readonly string[] | undefined;
|
|
56
|
+
/**
|
|
57
|
+
* Optional abort signal to cancel in-flight HTTP requests.
|
|
58
|
+
*/
|
|
59
|
+
readonly abortSignal?: AbortSignal | undefined;
|
|
60
|
+
/**
|
|
61
|
+
* Optional custom fetch implementation for testing or sandboxing.
|
|
62
|
+
*/
|
|
63
|
+
readonly customFetch?: typeof fetch | undefined;
|
|
64
|
+
/**
|
|
65
|
+
* Whether to inject a small random human-like delay before executing (default: true).
|
|
66
|
+
*/
|
|
67
|
+
readonly enableJitter?: boolean | undefined;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Individual organic search result item.
|
|
71
|
+
*/
|
|
72
|
+
export interface DuckDuckGoSearchResultItem {
|
|
73
|
+
/**
|
|
74
|
+
* Result title in clean text.
|
|
75
|
+
*/
|
|
76
|
+
readonly title: string;
|
|
77
|
+
/**
|
|
78
|
+
* Clean, canonical target URL (unwrapped from DuckDuckGo redirect).
|
|
79
|
+
*/
|
|
80
|
+
readonly url: string;
|
|
81
|
+
/**
|
|
82
|
+
* Domain name of the destination website.
|
|
83
|
+
*/
|
|
84
|
+
readonly domain: string;
|
|
85
|
+
/**
|
|
86
|
+
* Snippet description formatted in clean Markdown.
|
|
87
|
+
*/
|
|
88
|
+
readonly snippet: string;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Instant answer metadata from DuckDuckGo Instant Answer API.
|
|
92
|
+
*/
|
|
93
|
+
export interface DuckDuckGoInstantAnswer {
|
|
94
|
+
/**
|
|
95
|
+
* Entity or topic heading.
|
|
96
|
+
*/
|
|
97
|
+
readonly heading?: string | undefined;
|
|
98
|
+
/**
|
|
99
|
+
* Wikipedia or source abstract summary.
|
|
100
|
+
*/
|
|
101
|
+
readonly abstract?: string | undefined;
|
|
102
|
+
/**
|
|
103
|
+
* Name of the abstract provider (e.g. "Wikipedia").
|
|
104
|
+
*/
|
|
105
|
+
readonly source?: string | undefined;
|
|
106
|
+
/**
|
|
107
|
+
* Direct URL to the full source article.
|
|
108
|
+
*/
|
|
109
|
+
readonly sourceUrl?: string | undefined;
|
|
110
|
+
/**
|
|
111
|
+
* Related entity topic links.
|
|
112
|
+
*/
|
|
113
|
+
readonly relatedTopics?: readonly {
|
|
114
|
+
readonly text: string;
|
|
115
|
+
readonly url: string;
|
|
116
|
+
}[] | undefined;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Complete structured output returned by DuckDuckGo engine.
|
|
120
|
+
*/
|
|
121
|
+
export interface DuckDuckGoSearchResult {
|
|
122
|
+
/**
|
|
123
|
+
* Original query searched.
|
|
124
|
+
*/
|
|
125
|
+
readonly query: string;
|
|
126
|
+
/**
|
|
127
|
+
* Array of parsed organic search result items.
|
|
128
|
+
*/
|
|
129
|
+
readonly results: readonly DuckDuckGoSearchResultItem[];
|
|
130
|
+
/**
|
|
131
|
+
* Total number of results returned in this response.
|
|
132
|
+
*/
|
|
133
|
+
readonly totalResults: number;
|
|
134
|
+
/**
|
|
135
|
+
* Current pagination offset index.
|
|
136
|
+
*/
|
|
137
|
+
readonly offset: number;
|
|
138
|
+
/**
|
|
139
|
+
* Offset for retrieving the next page of results, or undefined if no next page exists.
|
|
140
|
+
*/
|
|
141
|
+
readonly nextOffset?: number | undefined;
|
|
142
|
+
/**
|
|
143
|
+
* Whether subsequent result pages are available.
|
|
144
|
+
*/
|
|
145
|
+
readonly hasNextPage: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* Active session token (VQD) if provided by DuckDuckGo.
|
|
148
|
+
*/
|
|
149
|
+
readonly vqd?: string | undefined;
|
|
150
|
+
/**
|
|
151
|
+
* Optional instant answer summary when available.
|
|
152
|
+
*/
|
|
153
|
+
readonly instantAnswer?: DuckDuckGoInstantAnswer | undefined;
|
|
154
|
+
/**
|
|
155
|
+
* Formatted Markdown representation of all results and instant answers.
|
|
156
|
+
*/
|
|
157
|
+
readonly markdown: string;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Converts HTML snippet markup into clean, readable Markdown text.
|
|
161
|
+
*
|
|
162
|
+
* @param html - Raw HTML snippet string.
|
|
163
|
+
* @returns Clean Markdown string with entities decoded and excessive whitespace collapsed.
|
|
164
|
+
*/
|
|
165
|
+
export declare function convertSnippetToMarkdown(html: string): string;
|
|
166
|
+
/**
|
|
167
|
+
* Unwraps DuckDuckGo redirect tracking URLs into clean, canonical target URLs.
|
|
168
|
+
* Handles formats like `//duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com&rut=...`.
|
|
169
|
+
*
|
|
170
|
+
* @param rawUrl - The raw URL string from DuckDuckGo search results.
|
|
171
|
+
* @returns Unwrapped canonical target URL.
|
|
172
|
+
*/
|
|
173
|
+
export declare function unwrapDuckDuckGoUrl(rawUrl: string): string;
|
|
174
|
+
/**
|
|
175
|
+
* Extracts the hostname domain from a URL safely.
|
|
176
|
+
*
|
|
177
|
+
* @param targetUrl - Valid URL string.
|
|
178
|
+
* @returns Hostname without leading "www.", or empty string on error.
|
|
179
|
+
*/
|
|
180
|
+
export declare function extractDomainFromUrl(targetUrl: string): string;
|
|
181
|
+
/**
|
|
182
|
+
* Checks whether a given target domain passes allowed and blocked domain filters.
|
|
183
|
+
*
|
|
184
|
+
* @param domain - Domain extracted from result URL.
|
|
185
|
+
* @param allowedDomains - Optional list of permitted domains.
|
|
186
|
+
* @param blockedDomains - Optional list of forbidden domains.
|
|
187
|
+
* @returns True if the domain passes all filters, false otherwise.
|
|
188
|
+
*/
|
|
189
|
+
export declare function isDomainAllowed(domain: string, allowedDomains?: readonly string[], blockedDomains?: readonly string[]): boolean;
|
|
190
|
+
/**
|
|
191
|
+
* Fetches instant answers from DuckDuckGo Instant Answer API.
|
|
192
|
+
*
|
|
193
|
+
* @param query - Search query.
|
|
194
|
+
* @param fetchFn - Fetch implementation.
|
|
195
|
+
* @param abortSignal - Optional abort signal.
|
|
196
|
+
* @returns Instant answer metadata if found, or undefined.
|
|
197
|
+
*/
|
|
198
|
+
export declare function fetchDuckDuckGoInstantAnswer(query: string, fetchFn: typeof fetch, abortSignal?: AbortSignal): Promise<DuckDuckGoInstantAnswer | undefined>;
|
|
199
|
+
/**
|
|
200
|
+
* Formats structured search results and instant answers into clean Markdown.
|
|
201
|
+
*
|
|
202
|
+
* @param query - Original search query.
|
|
203
|
+
* @param results - Array of organic search results.
|
|
204
|
+
* @param instant - Optional instant answer metadata.
|
|
205
|
+
* @param offset - Current page offset.
|
|
206
|
+
* @returns Clean, structured Markdown representation.
|
|
207
|
+
*/
|
|
208
|
+
export declare function formatSearchResultsToMarkdown(query: string, results: readonly DuckDuckGoSearchResultItem[], instant?: DuckDuckGoInstantAnswer, offset?: number): string;
|
|
209
|
+
/**
|
|
210
|
+
* Executes a DuckDuckGo search query using primary GET html.duckduckgo.com with automatic
|
|
211
|
+
* failover to lite.duckduckgo.com, URL unwrapping, filtering, and Markdown formatting.
|
|
212
|
+
*
|
|
213
|
+
* @param options - Configured search options.
|
|
214
|
+
* @returns Complete structured search result including formatted Markdown.
|
|
215
|
+
*/
|
|
216
|
+
export declare function executeDuckDuckGoSearch(options: DuckDuckGoSearchOptions): Promise<DuckDuckGoSearchResult>;
|
|
217
|
+
//# sourceMappingURL=duckDuckGo.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"duckDuckGo.d.ts","sources":["../../../src/tools/internal/duckDuckGo.ts"],"names":[],"mappings":"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"}
|