@fffangchenghao/dsh-web-search 0.14.0 → 0.16.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.
package/lib/keys.d.ts ADDED
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Credential rotation for the one optional key this plugin understands.
3
+ *
4
+ * AnySearch is the only engine with a credential, and it is optional: without a
5
+ * key the plugin stays anonymous at a lower rate limit. A user who does hold
6
+ * several keys should not have to edit Settings when one runs out mid-day, so
7
+ * the plugin accepts a list and rotates through it. A key that answers 401 is
8
+ * retired until Settings change; a key that answers 429 rests on an exponential
9
+ * schedule, exactly like a throttled engine.
10
+ *
11
+ * The pool lives outside the search run because its whole point is memory: the
12
+ * second request must know that the first key ran out. Pools are cached by the
13
+ * raw Settings string, so editing the field creates a fresh pool and reverting
14
+ * it restores the old one.
15
+ *
16
+ * @module @fangchenghao/dsh-web-search/keys
17
+ */
18
+ /** Why a key was set aside. */
19
+ export type KeyFailureKind = 'unauthorized' | 'throttled' | 'blocked';
20
+ /** The part of an error this module classifies. */
21
+ export interface KeyFailureLike {
22
+ code?: string;
23
+ message?: string;
24
+ }
25
+ /** Tunable cooldowns. */
26
+ export interface KeyPoolOptions {
27
+ /** Clock, for tests. */
28
+ now?: () => number;
29
+ /** How long a rejected key is retired, in ms. */
30
+ unauthorizedCooldownMs?: number;
31
+ /** First throttle rest, doubling per consecutive throttle. */
32
+ throttleBaseMs?: number;
33
+ /** Ceiling for the throttle rest. */
34
+ throttleMaxMs?: number;
35
+ /** How long a forbidden key rests. */
36
+ blockedCooldownMs?: number;
37
+ }
38
+ /**
39
+ * Split a Settings value into usable keys.
40
+ * @param raw - comma/newline/space separated keys, or a single key.
41
+ * @returns distinct keys, in the order given.
42
+ */
43
+ export declare function parseApiKeys(raw: unknown): string[];
44
+ /**
45
+ * Decide whether an error blames the key rather than the engine.
46
+ * @param error - classified search or fetch failure.
47
+ * @returns the kind of key failure, or `undefined` when the key is not at fault.
48
+ */
49
+ export declare function keyFailureKind(error: KeyFailureLike | undefined): KeyFailureKind | undefined;
50
+ /**
51
+ * A rotating set of keys with per-key cooldowns.
52
+ *
53
+ * `pick` never returns a resting key; when every key rests it returns
54
+ * `undefined` and callers fall back to anonymous access. That is deliberate: a
55
+ * rejected key retried immediately is how a temporary 429 becomes a longer
56
+ * ban.
57
+ */
58
+ export declare class KeyPool {
59
+ readonly keys: readonly string[];
60
+ private readonly states;
61
+ private readonly now;
62
+ private readonly unauthorizedMs;
63
+ private readonly throttleBaseMs;
64
+ private readonly throttleMaxMs;
65
+ private readonly blockedMs;
66
+ private cursor;
67
+ constructor(keys: readonly string[], options?: KeyPoolOptions);
68
+ /** Number of configured keys. */
69
+ get size(): number;
70
+ /** True when every configured key is resting. */
71
+ allCooling(now?: number): boolean;
72
+ /** Milliseconds until this key may be used again; 0 means now. */
73
+ cooldownLeft(key: string, now?: number): number;
74
+ /**
75
+ * Take the next available key, round-robin.
76
+ * @param now - clock override.
77
+ * @returns a usable key, or `undefined` when none is configured or all rest.
78
+ */
79
+ pick(now?: number): string | undefined;
80
+ /**
81
+ * Record that a key worked: clear its strikes and any rest.
82
+ * @param key - the key that answered.
83
+ */
84
+ reward(key: string): void;
85
+ /**
86
+ * Rest a key after a failure it caused.
87
+ * @param key - the rejected key.
88
+ * @param kind - why it was rejected.
89
+ * @param now - clock override.
90
+ * @returns milliseconds until the key may be tried again.
91
+ */
92
+ penalize(key: string, kind: KeyFailureKind, now?: number): number;
93
+ }
94
+ /**
95
+ * Get or create the pool for a Settings value.
96
+ * @param raw - the `anysearchApiKey` field.
97
+ * @returns a stable pool for this key list.
98
+ */
99
+ export declare function keyPoolFor(raw: string | undefined): KeyPool;
100
+ /** Drop cached pools; used by tests and after a Settings save. */
101
+ export declare function resetKeyPools(): void;
package/lib/keys.js ADDED
@@ -0,0 +1,163 @@
1
+ /**
2
+ * Credential rotation for the one optional key this plugin understands.
3
+ *
4
+ * AnySearch is the only engine with a credential, and it is optional: without a
5
+ * key the plugin stays anonymous at a lower rate limit. A user who does hold
6
+ * several keys should not have to edit Settings when one runs out mid-day, so
7
+ * the plugin accepts a list and rotates through it. A key that answers 401 is
8
+ * retired until Settings change; a key that answers 429 rests on an exponential
9
+ * schedule, exactly like a throttled engine.
10
+ *
11
+ * The pool lives outside the search run because its whole point is memory: the
12
+ * second request must know that the first key ran out. Pools are cached by the
13
+ * raw Settings string, so editing the field creates a fresh pool and reverting
14
+ * it restores the old one.
15
+ *
16
+ * @module @fangchenghao/dsh-web-search/keys
17
+ */
18
+ /** Seconds in a day, used for the 401 rest. */
19
+ const DAY_MS = 86_400_000;
20
+ /** Keys separated by anything a person might type. */
21
+ const SEPARATOR = /[\s,;]+/u;
22
+ /** Placeholder-looking values users paste from documentation. */
23
+ const PLACEHOLDER = /^(?:your[-_ ]?key|api[-_ ]?key|token|none|null|undefined|x{3,})$/iu;
24
+ /**
25
+ * Split a Settings value into usable keys.
26
+ * @param raw - comma/newline/space separated keys, or a single key.
27
+ * @returns distinct keys, in the order given.
28
+ */
29
+ export function parseApiKeys(raw) {
30
+ if (typeof raw !== 'string')
31
+ return [];
32
+ const seen = new Set();
33
+ const keys = [];
34
+ for (const part of raw.split(SEPARATOR)) {
35
+ const key = part.trim();
36
+ if (key.length === 0 || PLACEHOLDER.test(key) || seen.has(key))
37
+ continue;
38
+ seen.add(key);
39
+ keys.push(key);
40
+ }
41
+ return keys;
42
+ }
43
+ /**
44
+ * Decide whether an error blames the key rather than the engine.
45
+ * @param error - classified search or fetch failure.
46
+ * @returns the kind of key failure, or `undefined` when the key is not at fault.
47
+ */
48
+ export function keyFailureKind(error) {
49
+ if (error === undefined)
50
+ return undefined;
51
+ if (error.code === 'SEARCH_THROTTLED')
52
+ return 'throttled';
53
+ const message = error.message ?? '';
54
+ if (/HTTP 401|invalid api key|api key (?:is )?invalid|unauthori[sz]ed/iu.test(message))
55
+ return 'unauthorized';
56
+ if (/HTTP 403|forbidden/iu.test(message))
57
+ return 'blocked';
58
+ return undefined;
59
+ }
60
+ /**
61
+ * A rotating set of keys with per-key cooldowns.
62
+ *
63
+ * `pick` never returns a resting key; when every key rests it returns
64
+ * `undefined` and callers fall back to anonymous access. That is deliberate: a
65
+ * rejected key retried immediately is how a temporary 429 becomes a longer
66
+ * ban.
67
+ */
68
+ export class KeyPool {
69
+ keys;
70
+ states = new Map();
71
+ now;
72
+ unauthorizedMs;
73
+ throttleBaseMs;
74
+ throttleMaxMs;
75
+ blockedMs;
76
+ cursor = 0;
77
+ constructor(keys, options = {}) {
78
+ this.keys = [...keys];
79
+ this.now = options.now ?? Date.now;
80
+ this.unauthorizedMs = options.unauthorizedCooldownMs ?? DAY_MS;
81
+ this.throttleBaseMs = options.throttleBaseMs ?? 60_000;
82
+ this.throttleMaxMs = options.throttleMaxMs ?? 1_800_000;
83
+ this.blockedMs = options.blockedCooldownMs ?? 600_000;
84
+ }
85
+ /** Number of configured keys. */
86
+ get size() {
87
+ return this.keys.length;
88
+ }
89
+ /** True when every configured key is resting. */
90
+ allCooling(now = this.now()) {
91
+ return this.keys.length > 0 && this.keys.every((key) => this.cooldownLeft(key, now) > 0);
92
+ }
93
+ /** Milliseconds until this key may be used again; 0 means now. */
94
+ cooldownLeft(key, now = this.now()) {
95
+ const state = this.states.get(key);
96
+ return state === undefined ? 0 : Math.max(0, state.cooldownUntil - now);
97
+ }
98
+ /**
99
+ * Take the next available key, round-robin.
100
+ * @param now - clock override.
101
+ * @returns a usable key, or `undefined` when none is configured or all rest.
102
+ */
103
+ pick(now = this.now()) {
104
+ const count = this.keys.length;
105
+ if (count === 0)
106
+ return undefined;
107
+ for (let offset = 0; offset < count; offset += 1) {
108
+ const index = (this.cursor + offset) % count;
109
+ const key = this.keys[index];
110
+ if (this.cooldownLeft(key, now) === 0) {
111
+ this.cursor = (index + 1) % count;
112
+ return key;
113
+ }
114
+ }
115
+ return undefined;
116
+ }
117
+ /**
118
+ * Record that a key worked: clear its strikes and any rest.
119
+ * @param key - the key that answered.
120
+ */
121
+ reward(key) {
122
+ this.states.set(key, { cooldownUntil: 0, strikes: 0 });
123
+ }
124
+ /**
125
+ * Rest a key after a failure it caused.
126
+ * @param key - the rejected key.
127
+ * @param kind - why it was rejected.
128
+ * @param now - clock override.
129
+ * @returns milliseconds until the key may be tried again.
130
+ */
131
+ penalize(key, kind, now = this.now()) {
132
+ const previous = this.states.get(key);
133
+ const strikes = kind === 'throttled' ? (previous?.strikes ?? 0) + 1 : (previous?.strikes ?? 0);
134
+ const rest = kind === 'unauthorized'
135
+ ? this.unauthorizedMs
136
+ : kind === 'blocked'
137
+ ? this.blockedMs
138
+ : Math.min(this.throttleMaxMs, this.throttleBaseMs * 2 ** Math.max(0, strikes - 1));
139
+ this.states.set(key, { cooldownUntil: now + rest, strikes });
140
+ return rest;
141
+ }
142
+ }
143
+ /** Pools keyed by the exact Settings value, so an edit starts clean. */
144
+ const pools = new Map();
145
+ /**
146
+ * Get or create the pool for a Settings value.
147
+ * @param raw - the `anysearchApiKey` field.
148
+ * @returns a stable pool for this key list.
149
+ */
150
+ export function keyPoolFor(raw) {
151
+ const keys = parseApiKeys(raw ?? '');
152
+ const signature = keys.join('\n');
153
+ const existing = pools.get(signature);
154
+ if (existing !== undefined)
155
+ return existing;
156
+ const created = new KeyPool(keys);
157
+ pools.set(signature, created);
158
+ return created;
159
+ }
160
+ /** Drop cached pools; used by tests and after a Settings save. */
161
+ export function resetKeyPools() {
162
+ pools.clear();
163
+ }
package/lib/parsers.d.ts CHANGED
@@ -90,3 +90,28 @@ export declare function parseAnySearch(payload: string, baseUrl: string): Source
90
90
  * @returns whether the payload contains a distinctive query token.
91
91
  */
92
92
  export declare function echoesQuery(payload: string, query: string): boolean;
93
+ /**
94
+ * Parse the Firecrawl `/v1/search` JSON API.
95
+ *
96
+ * The endpoint is credential-free and answers
97
+ * `{ success: true, data: [{ title, url, description }] }`, where `description`
98
+ * is the page's extracted Markdown rather than a search snippet. Only the
99
+ * opening prose is kept: a whole page in one snippet would push every other
100
+ * engine's result out of the model-facing row.
101
+ * @param payload - the response body.
102
+ * @param baseUrl - the endpoint URL, used to resolve relative links.
103
+ * @returns parsed sources in the served order; empty on drift.
104
+ */
105
+ export declare function parseFirecrawl(payload: string, baseUrl: string): Source[];
106
+ /**
107
+ * Parse an Exa MCP `web_search_exa` answer.
108
+ *
109
+ * The MCP server replies with one SSE frame whose `text` content lists results
110
+ * as `Title: … / URL: … / Published: … / Author: … / Highlights: …` blocks
111
+ * separated by `---`. The block is the only stable shape here, so it is parsed
112
+ * line-wise; anything unexpected yields fewer rows, never an exception.
113
+ * @param payload - the raw SSE body.
114
+ * @param baseUrl - the MCP endpoint, used to resolve relative links.
115
+ * @returns parsed sources in the served order; empty on drift.
116
+ */
117
+ export declare function parseExaMcp(payload: string, baseUrl: string): Source[];
package/lib/parsers.js CHANGED
@@ -354,3 +354,142 @@ export function echoesQuery(payload, query) {
354
354
  const lower = payload.toLowerCase();
355
355
  return tokens.some((token) => lower.includes(token));
356
356
  }
357
+ /**
358
+ * Parse the Firecrawl `/v1/search` JSON API.
359
+ *
360
+ * The endpoint is credential-free and answers
361
+ * `{ success: true, data: [{ title, url, description }] }`, where `description`
362
+ * is the page's extracted Markdown rather than a search snippet. Only the
363
+ * opening prose is kept: a whole page in one snippet would push every other
364
+ * engine's result out of the model-facing row.
365
+ * @param payload - the response body.
366
+ * @param baseUrl - the endpoint URL, used to resolve relative links.
367
+ * @returns parsed sources in the served order; empty on drift.
368
+ */
369
+ export function parseFirecrawl(payload, baseUrl) {
370
+ let body;
371
+ try {
372
+ body = JSON.parse(payload);
373
+ }
374
+ catch {
375
+ return [];
376
+ }
377
+ if (!isRecord(body) || body.success !== true)
378
+ return [];
379
+ const rows = body.data;
380
+ if (!Array.isArray(rows))
381
+ return [];
382
+ const sources = [];
383
+ for (const row of rows) {
384
+ if (!isRecord(row))
385
+ continue;
386
+ const url = resolveHref(typeof row.url === 'string' ? row.url : undefined, baseUrl);
387
+ if (url === undefined)
388
+ continue;
389
+ const title = typeof row.title === 'string' ? row.title.trim() : '';
390
+ const description = typeof row.description === 'string' ? row.description : '';
391
+ const snippet = excerpt(description, 240);
392
+ sources.push({
393
+ url,
394
+ ...(title ? { title } : {}),
395
+ ...(snippet ? { snippet } : {}),
396
+ });
397
+ }
398
+ return sources;
399
+ }
400
+ /**
401
+ * Parse an Exa MCP `web_search_exa` answer.
402
+ *
403
+ * The MCP server replies with one SSE frame whose `text` content lists results
404
+ * as `Title: … / URL: … / Published: … / Author: … / Highlights: …` blocks
405
+ * separated by `---`. The block is the only stable shape here, so it is parsed
406
+ * line-wise; anything unexpected yields fewer rows, never an exception.
407
+ * @param payload - the raw SSE body.
408
+ * @param baseUrl - the MCP endpoint, used to resolve relative links.
409
+ * @returns parsed sources in the served order; empty on drift.
410
+ */
411
+ export function parseExaMcp(payload, baseUrl) {
412
+ if (typeof payload !== 'string' || payload.length === 0)
413
+ return [];
414
+ const texts = [];
415
+ for (const line of payload.split(/\r?\n/)) {
416
+ if (!line.startsWith('data:'))
417
+ continue;
418
+ const chunk = line.slice(5).trim();
419
+ if (chunk.length === 0 || chunk === '[DONE]')
420
+ continue;
421
+ try {
422
+ const frame = JSON.parse(chunk);
423
+ if (!isRecord(frame))
424
+ continue;
425
+ const result = frame.result;
426
+ if (!isRecord(result))
427
+ continue;
428
+ const content = result.content;
429
+ if (!Array.isArray(content))
430
+ continue;
431
+ for (const item of content) {
432
+ if (isRecord(item) && item.type === 'text' && typeof item.text === 'string')
433
+ texts.push(item.text);
434
+ }
435
+ }
436
+ catch {
437
+ // A non-JSON frame is not fatal: the remaining frames may still parse.
438
+ }
439
+ }
440
+ if (texts.length === 0)
441
+ return [];
442
+ const sources = [];
443
+ for (const block of texts.join('\n').split(/\n-{3,}\n?/u)) {
444
+ const lines = block.split(/\r?\n/);
445
+ let title = '';
446
+ let url;
447
+ const highlights = [];
448
+ let inHighlights = false;
449
+ for (const line of lines) {
450
+ if (/^title\s*:/i.test(line)) {
451
+ title = line.replace(/^title\s*:/i, '').trim();
452
+ inHighlights = false;
453
+ }
454
+ else if (/^url\s*:/i.test(line)) {
455
+ url = resolveHref(line.replace(/^url\s*:/i, '').trim(), baseUrl);
456
+ inHighlights = false;
457
+ }
458
+ else if (/^highlights\s*:/i.test(line)) {
459
+ inHighlights = true;
460
+ }
461
+ else if (/^(published|author)\s*:/i.test(line)) {
462
+ inHighlights = false;
463
+ }
464
+ else if (inHighlights) {
465
+ highlights.push(line);
466
+ }
467
+ }
468
+ if (url === undefined)
469
+ continue;
470
+ const snippet = excerpt(highlights.join(' '), 240);
471
+ sources.push({
472
+ url,
473
+ ...(title ? { title } : {}),
474
+ ...(snippet ? { snippet } : {}),
475
+ });
476
+ }
477
+ return sources;
478
+ }
479
+ /**
480
+ * Flatten a Markdown-ish page extract into one snippet line.
481
+ * @param raw - the text to flatten.
482
+ * @param max - the character ceiling.
483
+ * @returns a single trimmed line, possibly empty.
484
+ */
485
+ function excerpt(raw, max) {
486
+ const flattened = raw
487
+ .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
488
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
489
+ .replace(/^#{1,6}\s+/gm, '')
490
+ .replace(/\s+/g, ' ')
491
+ .trim();
492
+ if (flattened.length <= max)
493
+ return flattened;
494
+ return `${flattened.slice(0, max - 1).trimEnd()}…`;
495
+ }
@@ -0,0 +1,158 @@
1
+ /**
2
+ * The model-facing `research` tool: one call that searches, opens the best
3
+ * pages, and returns an evidence pack with the citations already attached.
4
+ *
5
+ * `web_search` answers "what links exist" and `web_fetch` answers "read this
6
+ * page". The step the model keeps doing by hand is the middle one: pick the
7
+ * two or three rows that matter, fetch them without timing out, and keep track
8
+ * of which sentence came from which URL. This tool performs exactly that step:
9
+ * it runs up to three searches through the normal engine path, de-duplicates
10
+ * the rows, fetches the leading pages through the same ladder `web_fetch` uses,
11
+ * and returns one Markdown document in which every excerpt sits under its URL.
12
+ *
13
+ * Failure is part of the contract. A page that will not load is reported by
14
+ * URL and reason, the remaining pages still arrive, and a total fetch failure
15
+ * still returns the search rows — a research call that found links but could
16
+ * not open them is still useful evidence.
17
+ *
18
+ * @module @fangchenghao/dsh-web-search/research
19
+ */
20
+ import type { Source } from './types.ts';
21
+ import type { ToolContent, ToolJsonSchema } from './domain-tool.ts';
22
+ /** The name this tool prefers. */
23
+ export declare const RESEARCH_TOOL_NAME = "research";
24
+ /** The name used when another plugin already registered `research`. */
25
+ export declare const RESEARCH_TOOL_FALLBACK_NAME = "web_research";
26
+ /** Pages fetched when the call names no budget. */
27
+ export declare const RESEARCH_DEFAULT_SOURCES = 3;
28
+ /** Smallest fetch budget a call may ask for. */
29
+ export declare const RESEARCH_MIN_SOURCES = 1;
30
+ /** Largest fetch budget a call may ask for. */
31
+ export declare const RESEARCH_MAX_SOURCES = 5;
32
+ /** Distinct queries accepted in one call. */
33
+ export declare const RESEARCH_MAX_QUERIES = 3;
34
+ /** Characters kept from each fetched page. */
35
+ export declare const RESEARCH_EXCERPT_CHARS = 1200;
36
+ /** Pages fetched at the same time. */
37
+ export declare const RESEARCH_PAGE_CONCURRENCY = 3;
38
+ /** Wall-clock budget for the whole call, below the tool's host timeout. */
39
+ export declare const RESEARCH_BUDGET_MS = 45000;
40
+ /** What one search reports to the tool. */
41
+ export interface ResearchSearchOutcome {
42
+ sources: Source[];
43
+ failures: string[];
44
+ }
45
+ /** Runs one query through the plugin's normal engine path. */
46
+ export type ResearchSearcher = (query: string, limit: number, signal?: AbortSignal) => Promise<ResearchSearchOutcome>;
47
+ /** What the fetch ladder reports for one URL. */
48
+ export interface ResearchFetchedPage {
49
+ url: string;
50
+ status: number;
51
+ text: string;
52
+ truncated: boolean;
53
+ }
54
+ /** Fetches one URL through the plugin's normal ladder. */
55
+ export type ResearchFetcher = (url: string, signal?: AbortSignal) => Promise<ResearchFetchedPage>;
56
+ /** One page in the evidence pack. */
57
+ export interface ResearchPage {
58
+ url: string;
59
+ title?: string;
60
+ status: number;
61
+ chars: number;
62
+ excerpt: string;
63
+ truncated: boolean;
64
+ }
65
+ /** A URL the call found but could not turn into evidence. */
66
+ export interface ResearchFetchFailure {
67
+ url: string;
68
+ reason: string;
69
+ }
70
+ /** What the tool returns to the model. */
71
+ export interface ResearchValue {
72
+ /** The query exactly as accepted (trimmed). */
73
+ query: string;
74
+ /** Every query the call actually ran. */
75
+ queries: string[];
76
+ /** Fetched pages, in the order they were chosen. */
77
+ pages: ResearchPage[];
78
+ /** Rows that were found but not fetched, with their titles when known. */
79
+ sources: Array<{
80
+ url: string;
81
+ title?: string;
82
+ }>;
83
+ /** Fetch failures, one entry per URL. */
84
+ failures: ResearchFetchFailure[];
85
+ /** Number of search rows seen before the fetch budget cut them. */
86
+ found: number;
87
+ /** True when the search row list was cut by the fetch budget. */
88
+ truncated: boolean;
89
+ }
90
+ /** A tool definition in the registry's native shape. */
91
+ export interface ResearchDefinition {
92
+ name: string;
93
+ description: string;
94
+ parameters: ToolJsonSchema;
95
+ output: {
96
+ schema: ToolJsonSchema;
97
+ render: (args: unknown, value: ResearchValue) => ToolContent[];
98
+ };
99
+ timeoutMs?: number;
100
+ isConcurrencySafe?: (args: unknown) => boolean;
101
+ execute: (args: unknown, exec: {
102
+ signal?: AbortSignal;
103
+ }) => Promise<ResearchValue>;
104
+ }
105
+ /** The slice of the tool registry this module needs. */
106
+ export interface ResearchRegistryLike {
107
+ register(definition: ResearchDefinition): unknown;
108
+ get?(name: string, scope?: unknown): unknown;
109
+ }
110
+ /** Construction seams. */
111
+ export interface ResearchOptions {
112
+ /** Registration diagnostics. */
113
+ warn?: (message: string) => void;
114
+ }
115
+ /** A successful registration plus the exact way to undo it. */
116
+ export interface ResearchRegistration {
117
+ name: string;
118
+ dispose: () => void;
119
+ }
120
+ /**
121
+ * Canonical form used to decide whether two rows are the same page.
122
+ *
123
+ * Search engines disagree about `www.`, trailing slashes and fragments; two
124
+ * rows that differ only in those are one page, and fetching both wastes the
125
+ * whole budget.
126
+ * @param raw - candidate URL.
127
+ * @returns a stable key, or `undefined` for a non-http(s) URL.
128
+ */
129
+ export declare function canonicalKey(raw: string): string | undefined;
130
+ /**
131
+ * Format the evidence pack the model reads.
132
+ * @param value - what the call produced.
133
+ * @returns a Markdown document with one section per fetched page.
134
+ */
135
+ export declare function formatResearchValue(value: ResearchValue): string;
136
+ /**
137
+ * Build the tool definition the host registry accepts.
138
+ * @param name - `research`, or the fallback when that name is taken.
139
+ * @param search - runs one query through the plugin's search path.
140
+ * @param fetchPage - fetches one URL through the plugin's fetch ladder.
141
+ * @returns a registry-ready definition.
142
+ */
143
+ export declare function createResearchDefinition(name: string, search: ResearchSearcher, fetchPage: ResearchFetcher): ResearchDefinition;
144
+ /**
145
+ * Pick the tool name this deployment can accept.
146
+ * @param tools - the live registry.
147
+ * @returns the preferred or fallback name.
148
+ */
149
+ export declare function pickResearchToolName(tools: ResearchRegistryLike): string;
150
+ /**
151
+ * Register the tool when a registry is available.
152
+ * @param tools - the live registry.
153
+ * @param search - executes one search through the plugin's normal path.
154
+ * @param fetchPage - fetches one URL through the plugin's fetch ladder.
155
+ * @param options - diagnostics.
156
+ * @returns the registered name and its disposer, or `undefined` when skipped.
157
+ */
158
+ export declare function registerResearchTool(tools: ResearchRegistryLike, search: ResearchSearcher, fetchPage: ResearchFetcher, options?: ResearchOptions): ResearchRegistration | undefined;