@astratra/ai 1.4.0 → 1.6.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.
@@ -13,7 +13,7 @@
13
13
  * and never the key.
14
14
  */
15
15
 
16
- const THINK = /<think>[\s\S]*?(?:<\/think>|$)/gi;
16
+ const { providerResult, readToolArguments, readWrittenAnswer, readWrittenToolCalls, toolCallOf, withoutThinking } = require('./modelAnswers');
17
17
 
18
18
  function toTranscript(messages) {
19
19
  return (Array.isArray(messages) ? messages : []).map((message) => {
@@ -25,7 +25,8 @@ function toTranscript(messages) {
25
25
  tool_calls: message.toolCalls.map((call) => ({
26
26
  id: call.id,
27
27
  type: 'function',
28
- function: { name: call.name, arguments: JSON.stringify(call.args === undefined ? {} : call.args) }
28
+ /* Des arguments illisibles (null) repartent en objet vide : le fournisseur refuserait « null ». */
29
+ function: { name: call.name, arguments: JSON.stringify(call.args && typeof call.args === 'object' ? call.args : {}) }
29
30
  }))
30
31
  } : {})
31
32
  };
@@ -49,18 +50,6 @@ function toTranscript(messages) {
49
50
  });
50
51
  }
51
52
 
52
- /** Tool arguments as an object, or null with `invalid: true` for anything else. */
53
- function readToolArguments(raw) {
54
- if (raw === undefined || raw === null || raw === '') return { args: {}, invalid: false };
55
- if (typeof raw === 'object') return { args: raw, invalid: false };
56
- try {
57
- const parsed = JSON.parse(String(raw));
58
- return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? { args: parsed, invalid: false } : { args: null, invalid: true };
59
- } catch (_error) {
60
- return { args: null, invalid: true };
61
- }
62
- }
63
-
64
53
  /**
65
54
  * Ask one model.
66
55
  * @param {{ url: string, key: string, model: string, extra?: object }} target
@@ -101,13 +90,12 @@ async function askChatModel(target, request, io = {}) {
101
90
  return {
102
91
  status: response.status,
103
92
  text: null,
104
- toolCalls: message.tool_calls.map((call) => {
105
- const { args, invalid } = readToolArguments(call.function && call.function.arguments);
106
- return { id: call.id, name: call.function && call.function.name, args, ...(invalid ? { invalid: true } : {}) };
107
- })
93
+ toolCalls: message.tool_calls.map((call) => toolCallOf(call.id, call.function && call.function.name, call.function && call.function.arguments))
108
94
  };
109
95
  }
110
- const text = String(message.content === null || message.content === undefined ? '' : message.content).replace(THINK, '').trim();
96
+ const text = withoutThinking(message.content);
97
+ const written = readWrittenAnswer(text, Boolean(request.tools && request.tools.length));
98
+ if (written) return { status: response.status, ...written };
111
99
  return { status: response.status, text, cut: choice.finish_reason === 'length' };
112
100
  }
113
101
 
@@ -116,55 +104,55 @@ async function askChatModel(target, request, io = {}) {
116
104
  *
117
105
  * @param {object} options
118
106
  * @param {string} options.id
119
- * @param {string} options.url
120
- * @param {Function} options.getKey () => key, read at every call: a key changed
107
+ * @param {string|Function} options.url or (ctx) => url, read at every call (an account id kept with the keys).
108
+ * @param {Function} options.getKey (ctx) => key, read at every call: a key changed
121
109
  * from the settings screen takes effect without a restart.
122
- * @param {object[]} options.models router model entries ({ id, rpm, rpd, tpd, complexity }).
123
- * @param {Function} options.fetch
110
+ * @param {object[]} options.models router model entries ({ id, rpm, rpd, tpd, complexity, extra? }).
111
+ * A model's `extra` joins the provider's for that model only.
112
+ * @param {Function} options.fetch `ctx.fetch`, when given, replaces it for one call.
124
113
  * @param {boolean} [options.external] false for a model on this machine: the router then does not mask.
125
- * @param {number} [options.timeoutMs]
114
+ * @param {number} [options.timeoutMs] `ctx.timeoutMs` replaces it for one call.
126
115
  * @param {object} [options.extra] joined to each request.
127
- * @param {Function} [options.toRequest] (prompt, ctx) => { system?, messages }. Default: the prompt as one user message.
116
+ * @param {Function} [options.lane] (ctx) => string | null — a key of its own for this use: the router rests it apart.
117
+ * @param {boolean} [options.detailed] true: the call resolves { text, toolCalls, cut } (an empty text
118
+ * included, for the router's `accepts` to judge) instead of the text alone.
119
+ * @param {Function} [options.toRequest] (prompt, ctx) => { system?, messages, tools?, maxTokens? }. Default: the prompt as one user message.
128
120
  */
129
121
  function createOpenAICompatibleProvider(options = {}) {
130
- for (const field of ['id', 'url']) {
131
- if (typeof options[field] !== 'string' || !options[field]) throw new Error(`createOpenAICompatibleProvider requires options.${field}.`);
122
+ if (typeof options.id !== 'string' || !options.id) throw new Error('createOpenAICompatibleProvider requires options.id.');
123
+ if (!(typeof options.url === 'function' || (typeof options.url === 'string' && options.url))) {
124
+ throw new Error('createOpenAICompatibleProvider requires options.url.');
132
125
  }
133
126
  if (typeof options.getKey !== 'function') throw new Error('createOpenAICompatibleProvider requires options.getKey.');
134
127
  if (typeof options.fetch !== 'function') throw new Error('createOpenAICompatibleProvider requires options.fetch.');
135
128
  const toRequest = options.toRequest || ((prompt) => ({ messages: [{ role: 'user', text: String(prompt) }] }));
129
+ const urlOf = (ctx) => (typeof options.url === 'function' ? options.url(ctx) : options.url);
136
130
 
137
131
  return {
138
132
  id: options.id,
139
133
  models: options.models || [],
140
134
  ...(options.external === false ? { external: false } : {}),
135
+ ...(typeof options.lane === 'function' ? { lane: options.lane } : {}),
136
+ /* Sans clé (ou sans adresse), le routeur saute ce fournisseur sans rien lui demander. */
137
+ async available(ctx = {}) {
138
+ return Boolean(urlOf(ctx)) && Boolean(await options.getKey(ctx));
139
+ },
141
140
  async call(prompt, ctx = {}, model = {}) {
142
- const key = await options.getKey();
143
- if (!key) {
141
+ const key = await options.getKey(ctx);
142
+ const url = urlOf(ctx);
143
+ if (!key || !url) {
144
144
  const missing = new Error(`Provider "${options.id}" has no key.`);
145
145
  missing.statusCode = 401;
146
146
  throw missing;
147
147
  }
148
148
  const answer = await askChatModel(
149
- { url: options.url, key, model: model.id, extra: options.extra },
149
+ { url, key, model: model.id, extra: { ...(options.extra || {}), ...(model.extra || {}) } },
150
150
  { maxTokens: model.maxTokens, ...toRequest(prompt, ctx) },
151
- { fetch: options.fetch, signal: ctx.signal, timeoutMs: options.timeoutMs }
151
+ { fetch: typeof ctx.fetch === 'function' ? ctx.fetch : options.fetch, signal: ctx.signal, timeoutMs: ctx.timeoutMs || options.timeoutMs }
152
152
  );
153
- if (answer.status < 200 || answer.status >= 300) {
154
- /* The status reaches the router (429 → cooldown); the key never does. */
155
- const failure = new Error(`Provider "${options.id}" answered ${answer.status}.`);
156
- failure.statusCode = answer.status;
157
- throw failure;
158
- }
159
- if (answer.toolCalls) return { toolCalls: answer.toolCalls };
160
- if (!answer.text) {
161
- const empty = new Error(`Provider "${options.id}" gave no text.`);
162
- empty.statusCode = 502;
163
- throw empty;
164
- }
165
- return answer.text;
153
+ return providerResult(options.id, answer, options.detailed);
166
154
  }
167
155
  };
168
156
  }
169
157
 
170
- module.exports = { askChatModel, createOpenAICompatibleProvider, readToolArguments };
158
+ module.exports = { askChatModel, createOpenAICompatibleProvider, readToolArguments, readWrittenToolCalls, withoutThinking };
@@ -45,7 +45,14 @@ function createProviderRouter(config = {}) {
45
45
  maxFailures: config.maxFailures ?? DEFAULT_MAX_FAILURES,
46
46
  degradedMs: config.degradedMs ?? DEFAULT_DEGRADED_MS,
47
47
  intentRouting: config.intentRouting || {},
48
- redisKeyPrefix: config.redisKeyPrefix || 'astratra:ai:provider'
48
+ redisKeyPrefix: config.redisKeyPrefix || 'astratra:ai:provider',
49
+ /* Ce qui met un modèle au repos. Par défaut un 429 ; un projet peut y
50
+ ajouter un 503 « surchargé » ou un délai dépassé. */
51
+ cooldownOn: typeof config.cooldownOn === 'function' ? config.cooldownOn : isRateLimitError,
52
+ /* 'try' : quand tous les candidats se reposent, on les essaie quand même —
53
+ un repos est une supposition, pas un refus. */
54
+ whenAllCooling: config.whenAllCooling === 'try' ? 'try' : 'skip',
55
+ now: typeof config.now === 'function' ? config.now : Date.now
49
56
  };
50
57
  /* One circuit per PROVIDER, never one for all: a provider that is down must
51
58
  not take the others with it. Optional — the per-model cooldown and
@@ -55,42 +62,68 @@ function createProviderRouter(config = {}) {
55
62
  let midnightTimer = null;
56
63
  const resetDailyAtMidnight = () => {
57
64
  resetDailyUsage(state);
58
- midnightTimer = setTimeout(resetDailyAtMidnight, msUntilNextMidnight());
65
+ midnightTimer = unref(setTimeout(resetDailyAtMidnight, msUntilNextMidnight()));
59
66
  };
60
- midnightTimer = setTimeout(resetDailyAtMidnight, msUntilNextMidnight());
67
+ /* Le minuteur ne garde jamais le processus en vie : un routeur créé au
68
+ chargement d'un module ne doit pas empêcher un script ou des tests de finir. */
69
+ midnightTimer = unref(setTimeout(resetDailyAtMidnight, msUntilNextMidnight()));
61
70
 
62
71
  const redis = createRedisLink(config, options);
63
72
  const redisReady = redis.connect().then(() => redis.restoreState(state)).catch(() => {});
64
73
 
65
74
 
66
- async function ask(prompt, request = {}, ctx = {}) {
75
+ /**
76
+ * Comme ask, mais dit aussi QUI a répondu : { value, provider, model, key, partial }.
77
+ * `key` est la clé d'état ("fournisseur:modèle", suivie de "@voie" quand le
78
+ * fournisseur a une voie pour cet appel).
79
+ */
80
+ async function route(prompt, request = {}, ctx = {}) {
67
81
  await redisReady;
68
- const candidates = selectCandidates(providers, options.intentRouting, request);
69
- const errors = [];
82
+ const signal = ctx && ctx.signal;
70
83
  const masker = ctx && ctx.masker && typeof ctx.masker.mask === 'function' ? ctx.masker : null;
71
84
  const providerCtx = masker ? withoutMasker(ctx) : ctx;
85
+ const accepts = typeof request.accepts === 'function' ? request.accepts : null;
86
+ const partial = typeof request.partial === 'function' ? request.partial : null;
87
+
88
+ /* Un fournisseur sans clé (ou éteint) est sauté sans bruit : ni quota, ni échec. */
89
+ const reachable = [];
90
+ for (const candidate of selectCandidates(providers, options.intentRouting, request)) {
91
+ if (typeof candidate.provider.available === 'function' && !(await candidate.provider.available(providerCtx))) continue;
92
+ reachable.push(candidate);
93
+ }
94
+ if (!reachable.length) throw unavailable('AI_NO_PROVIDER', 'No AI provider is available for this request.');
95
+ const matching = typeof request.select === 'function'
96
+ ? reachable.filter(({ provider, model }) => request.select(model, provider))
97
+ : reachable;
98
+ if (!matching.length) throw unavailable('AI_NO_MATCH', 'No available AI model matches this request.');
99
+
100
+ const keyed = matching.map((candidate) => ({ ...candidate, key: laneKey(candidate.provider, candidate.model, providerCtx) }));
101
+ const awake = keyed.filter(({ key, model }) => isModelAvailable(state, key, model, request, options.now()));
102
+ const tried = awake.length || options.whenAllCooling !== 'try' ? awake : keyed;
72
103
 
73
- for (const candidate of candidates) {
74
- const { provider, model } = candidate;
75
- const key = modelKey(provider, model);
76
- if (!isModelAvailable(state, key, model, request)) continue;
104
+ const errors = [];
105
+ let last = null;
106
+ let kept = null;
107
+ for (const { provider, model, key } of tried) {
108
+ stopIfAborted(signal);
77
109
  const reservation = await redis.reserveUsage(key, model, request);
78
110
  if (!reservation) continue;
79
111
 
80
- const undo = reserveUsage(state, key, request);
112
+ const undo = reserveUsage(state, key, request, options.now());
81
113
 
82
114
  /* Masked at the moment it leaves: a provider that runs on this machine
83
115
  (`external: false`) gets the text as it is. */
84
116
  const outbound = masker && provider.external !== false;
85
117
  const send = async () => provider.call(outbound ? await masker.maskAsync(prompt) : prompt, providerCtx, model);
86
118
 
119
+ let raw;
87
120
  try {
88
- const raw = breakers ? await breakers.run(provider.id, send) : await send();
89
- clearFailures(state, key);
90
- redis.mirrorFailures(key, state.models[key]);
91
- return outbound ? unmaskResult(masker, raw) : raw;
121
+ raw = breakers ? await breakers.run(provider.id, send) : await send();
92
122
  } catch (error) {
123
+ /* La personne est partie : rien n'a échoué, on s'arrête là. */
124
+ stopIfAborted(signal);
93
125
  errors.push(error);
126
+ last = `${key}: ${error && error.message}`;
94
127
  if (isCircuitOpen(error)) {
95
128
  /* The breaker refused before anything was sent: nothing was used,
96
129
  and the model itself did not fail. */
@@ -100,38 +133,72 @@ function createProviderRouter(config = {}) {
100
133
  }
101
134
  markFailure(state, key, error, options);
102
135
  redis.mirrorFailure(key, state.models[key]);
136
+ continue;
137
+ }
138
+ clearFailures(state, key);
139
+ redis.mirrorFailures(key, state.models[key]);
140
+ const value = outbound ? unmaskResult(masker, raw) : raw;
141
+ /* Une réponse coupée à sa longueur n'est pas donnée tant qu'un autre
142
+ modèle peut la finir : gardée en dernier recours. */
143
+ if (partial && partial(value) && (!accepts || accepts(value))) {
144
+ kept = kept || { value, provider: provider.id, model: model.id, key, partial: true };
145
+ last = `${key} stopped short`;
146
+ continue;
147
+ }
148
+ if (accepts && !accepts(value)) {
149
+ /* Une réponse que l'appelant refuse (outil inconnu, texte vide) passe
150
+ au modèle suivant ; ce n'est pas une panne du modèle. */
151
+ last = `${key} gave a response that was not accepted`;
152
+ continue;
103
153
  }
154
+ return { value, provider: provider.id, model: model.id, key, partial: false };
104
155
  }
105
156
 
106
- const suffix = errors.length ? ` Last error: ${errors[errors.length - 1].message}` : '';
107
- throw new AppError(`No available AI provider/model for this request.${suffix}`, 503);
157
+ if (kept) return kept;
158
+ const error = unavailable('AI_UNAVAILABLE', `No available AI provider/model for this request.${last ? ` Last error: ${last}` : ''}`);
159
+ error.errors = errors;
160
+ throw error;
161
+ }
162
+
163
+ async function ask(prompt, request = {}, ctx = {}) {
164
+ return (await route(prompt, request, ctx)).value;
108
165
  }
109
166
 
110
167
  function getStats() {
111
- const now = Date.now();
168
+ const now = options.now();
112
169
  const stats = {};
170
+ const entry = (providerId, model, modelState) => ({
171
+ provider: providerId,
172
+ rpm_now: currentRpm(modelState, now),
173
+ rpm_limit: model.rpm ?? null,
174
+ rpd_used: modelState.rpdUsed,
175
+ rpd_limit: model.rpd ?? null,
176
+ tpd_used: modelState.tpdUsed,
177
+ tpd_limit: model.tpd ?? null,
178
+ cooldown: isUntilActive(modelState.cooldownUntil, now),
179
+ degraded: isUntilActive(modelState.degradedUntil, now),
180
+ failures: modelState.failures || 0,
181
+ circuit: breakers ? breakers.stateOf(providerId) || 'closed' : null
182
+ });
113
183
  providers.forEach(provider => {
114
184
  (provider.models || []).forEach(model => {
115
185
  const key = modelKey(provider, model);
116
- const modelState = state.models[key] || createModelState();
117
- stats[key] = {
118
- provider: provider.id,
119
- rpm_now: currentRpm(modelState, now),
120
- rpm_limit: model.rpm ?? null,
121
- rpd_used: modelState.rpdUsed,
122
- rpd_limit: model.rpd ?? null,
123
- tpd_used: modelState.tpdUsed,
124
- tpd_limit: model.tpd ?? null,
125
- cooldown: isUntilActive(modelState.cooldownUntil, now),
126
- degraded: isUntilActive(modelState.degradedUntil, now),
127
- failures: modelState.failures || 0,
128
- circuit: breakers ? breakers.stateOf(provider.id) || 'closed' : null
129
- };
186
+ stats[key] = entry(provider.id, model, state.models[key] || createModelState());
130
187
  });
131
188
  });
189
+ /* Les modèles demandés par `request.candidates` et les voies n'existent
190
+ qu'une fois utilisés : ils apparaissent alors, sans limites déclarées. */
191
+ Object.entries(state.models).forEach(([key, modelState]) => {
192
+ if (!stats[key]) stats[key] = entry(key.split(':')[0], {}, modelState);
193
+ });
132
194
  return stats;
133
195
  }
134
196
 
197
+ /** Oublie repos, dégradations, échecs et usage (tests, remise à zéro manuelle). */
198
+ function reset() {
199
+ Object.keys(state.models).forEach((key) => { state.models[key] = createModelState(); });
200
+ }
201
+
135
202
  function stop() {
136
203
  if (midnightTimer) {
137
204
  clearTimeout(midnightTimer);
@@ -140,7 +207,7 @@ function createProviderRouter(config = {}) {
140
207
  redis.disconnect();
141
208
  }
142
209
 
143
- return { ask, getStats, stop, breakers };
210
+ return { ask, route, getStats, reset, stop, breakers };
144
211
  }
145
212
 
146
213
  /** A pool, a factory, or nothing. */
@@ -317,7 +384,30 @@ function createRedisLink(config, options) {
317
384
  return { connect, restoreState, reserveUsage, releaseUsage, mirrorFailure, mirrorFailures, disconnect };
318
385
  }
319
386
 
387
+ /*
388
+ * `request.candidates` : l'ordre de CETTE demande, à travers les fournisseurs
389
+ * ([{ provider, model, ...champs du modèle }]). Un projet a souvent plusieurs
390
+ * ordres pour les mêmes modèles (le plus rapide d'abord pour ce qu'on attend,
391
+ * le plus capable d'abord pour le reste). Un fournisseur inconnu est ignoré ;
392
+ * un modèle non déclaré par le fournisseur est pris tel que décrit.
393
+ */
394
+ function explicitCandidates(providers, list) {
395
+ const byId = new Map(providers.map((provider) => [provider.id, provider]));
396
+ return list.flatMap((entry) => {
397
+ const provider = entry && byId.get(entry.provider);
398
+ if (!provider || !entry.model) return [];
399
+ const fields = { ...entry };
400
+ delete fields.provider;
401
+ delete fields.model;
402
+ const declared = (provider.models || []).find((model) => model.id === entry.model);
403
+ return [{ provider, model: { ...(declared || {}), ...fields, id: entry.model } }];
404
+ });
405
+ }
406
+
320
407
  function selectCandidates(providers, intentRouting, request) {
408
+ if (Array.isArray(request.candidates)) {
409
+ return explicitCandidates(providers, request.candidates).filter(({ model }) => supportsComplexity(model, request.complexity));
410
+ }
321
411
  const preferred = request.intent && intentRouting[request.intent]
322
412
  ? intentRouting[request.intent].preferred || []
323
413
  : [];
@@ -345,8 +435,7 @@ function supportsComplexity(model, complexity) {
345
435
  return Array.isArray(model.complexity) && model.complexity.includes(complexity);
346
436
  }
347
437
 
348
- function isModelAvailable(state, key, model, request) {
349
- const now = Date.now();
438
+ function isModelAvailable(state, key, model, request, now) {
350
439
  const modelState = state.models[key] || createModelState();
351
440
  state.models[key] = modelState;
352
441
 
@@ -358,9 +447,8 @@ function isModelAvailable(state, key, model, request) {
358
447
  return true;
359
448
  }
360
449
 
361
- function reserveUsage(state, key, request) {
450
+ function reserveUsage(state, key, request, now) {
362
451
  const modelState = state.models[key] || createModelState();
363
- const now = Date.now();
364
452
  const tokens = estimatedTokens(request);
365
453
  modelState.rpmWindow = modelState.rpmWindow.filter(ts => now - ts < RPM_WINDOW_MS);
366
454
  modelState.rpmWindow.push(now);
@@ -393,12 +481,12 @@ function markFailure(state, modelId, error, options) {
393
481
  const modelState = state.models[modelId] || createModelState();
394
482
  modelState.failures = (modelState.failures || 0) + 1;
395
483
 
396
- if (isRateLimitError(error)) {
397
- modelState.cooldownUntil = Date.now() + options.cooldownMs + jitter(options.cooldownJitterMs);
484
+ if (options.cooldownOn(error)) {
485
+ modelState.cooldownUntil = options.now() + options.cooldownMs + jitter(options.cooldownJitterMs);
398
486
  }
399
487
 
400
488
  if (modelState.failures >= options.maxFailures) {
401
- modelState.degradedUntil = Date.now() + options.degradedMs;
489
+ modelState.degradedUntil = options.now() + options.degradedMs;
402
490
  }
403
491
 
404
492
  state.models[modelId] = modelState;
@@ -414,6 +502,32 @@ function modelKey(provider, model) {
414
502
  return `${provider.id}:${model.id}`;
415
503
  }
416
504
 
505
+ /*
506
+ * Une voie : une clé à part pour un usage (son propre quota gratuit). Elle se
507
+ * repose seule — une clé saturée par un travail de fond n'arrête jamais les
508
+ * conversations servies par la clé générale.
509
+ */
510
+ function laneKey(provider, model, ctx) {
511
+ const lane = typeof provider.lane === 'function' ? provider.lane(ctx) : null;
512
+ return lane ? `${modelKey(provider, model)}@${lane}` : modelKey(provider, model);
513
+ }
514
+
515
+ function unavailable(code, message) {
516
+ const error = new AppError(message, 503);
517
+ error.code = code;
518
+ return error;
519
+ }
520
+
521
+ /* Une demande abandonnée par l'appelant s'arrête net, avec la raison de l'appelant. */
522
+ function stopIfAborted(signal) {
523
+ if (signal && signal.aborted) throw signal.reason;
524
+ }
525
+
526
+ function unref(timer) {
527
+ if (timer && typeof timer.unref === 'function') timer.unref();
528
+ return timer;
529
+ }
530
+
417
531
  function isRateLimitError(error) {
418
532
  return error && (
419
533
  error.statusCode === 429 ||
@@ -1,9 +1,12 @@
1
+ const TOOL_RISKS = Object.freeze({ LOW: 0, MEDIUM: 1, HIGH: 2, UNKNOWN: 3 });
2
+
1
3
  function createToolRegistry() {
2
4
  const tools = [];
3
5
 
4
6
  function register(tool) {
5
7
  validateTool(tool);
6
- tools.push({ ...tool, roles: [...tool.roles], params: tool.params || {} });
8
+ const risk = normalizeRisk(tool.risk);
9
+ tools.push({ ...tool, risk, roles: [...tool.roles], params: tool.params || {} });
7
10
  return tool;
8
11
  }
9
12
 
@@ -40,8 +43,16 @@ function validateTool(tool) {
40
43
  if (!tool.type) throw new Error('tool.type is required');
41
44
  if (!Array.isArray(tool.roles)) throw new Error('tool.roles must be an array');
42
45
  if (typeof tool.handler !== 'function') throw new Error('tool.handler must be a function');
46
+ if (tool.risk !== undefined && !['LOW', 'MEDIUM', 'HIGH'].includes(String(tool.risk).toUpperCase())) {
47
+ throw new Error('tool.risk must be LOW, MEDIUM or HIGH');
48
+ }
49
+ }
50
+
51
+ function normalizeRisk(risk) {
52
+ return risk === undefined ? 'UNKNOWN' : String(risk).toUpperCase();
43
53
  }
44
54
 
45
55
  module.exports = {
46
- createToolRegistry
56
+ createToolRegistry,
57
+ TOOL_RISKS
47
58
  };
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Une recherche web pour un agent, au format Serper (résultats Google).
3
+ *
4
+ * Ce qui revient au modèle est tenu court et propre : des résultats https
5
+ * seulement, un titre obligatoire, au plus `num`, et un filtre de l'appelant
6
+ * (un site hostile, une source refusée) appliqué AVANT que le modèle ne lise.
7
+ * La clé part dans l'en-tête et n'apparaît dans aucune erreur.
8
+ */
9
+
10
+ const DEFAULT_ENDPOINT = 'https://google.serper.dev/search';
11
+ const DEFAULT_NUM = 8;
12
+ const DEFAULT_TIMEOUT_MS = 10_000;
13
+
14
+ function failure(code, message) {
15
+ const error = new Error(message);
16
+ error.code = code;
17
+ return error;
18
+ }
19
+
20
+ /**
21
+ * @param {object} search
22
+ * @param {string} search.query
23
+ * @param {string[]} [search.sites] la recherche restreinte à ces sites (site:a OR site:b).
24
+ * @param {string} [search.hl] la langue de l'interface de recherche.
25
+ * @param {number} [search.num] Défaut 8.
26
+ * @param {object} io
27
+ * @param {string} io.key
28
+ * @param {Function} io.fetch
29
+ * @param {Function} [io.accept] ({ title, url, snippet, date }, URL) => boolean — false : le résultat est écarté.
30
+ * @param {number} [io.timeoutMs] Défaut 10 s.
31
+ * @param {string} [io.endpoint]
32
+ * @returns {Promise<{ title: string, url: string, snippet: string, date: string|null }[]>}
33
+ * @throws {Error} code 'WEB_SEARCH_NO_KEY' sans clé (rien n'est demandé), 'WEB_SEARCH_FAILED' sinon.
34
+ */
35
+ async function searchSerper(search = {}, io = {}) {
36
+ if (!io.key) throw failure('WEB_SEARCH_NO_KEY', 'no key');
37
+ if (typeof io.fetch !== 'function') throw new Error('searchSerper requires io.fetch.');
38
+ const num = search.num || DEFAULT_NUM;
39
+ const scope = (search.sites || []).map((site) => `site:${site}`).join(' OR ');
40
+ let answer;
41
+ try {
42
+ const response = await io.fetch(io.endpoint || DEFAULT_ENDPOINT, {
43
+ method: 'POST',
44
+ headers: { 'X-API-KEY': io.key, 'content-type': 'application/json' },
45
+ body: JSON.stringify({ q: scope ? `${search.query} ${scope}` : search.query, num, ...(search.hl ? { hl: search.hl } : {}) }),
46
+ signal: globalThis.AbortSignal.timeout(io.timeoutMs || DEFAULT_TIMEOUT_MS)
47
+ });
48
+ if (!response.ok) throw new Error(`Serper answered ${response.status}`);
49
+ answer = await response.json();
50
+ } catch (error) {
51
+ throw failure('WEB_SEARCH_FAILED', error.message);
52
+ }
53
+ const accept = typeof io.accept === 'function' ? io.accept : () => true;
54
+ return (Array.isArray(answer?.organic) ? answer.organic : [])
55
+ .flatMap((result) => {
56
+ let url;
57
+ try {
58
+ url = new URL(String(result?.link));
59
+ } catch (_error) {
60
+ return [];
61
+ }
62
+ const title = typeof result.title === 'string' ? result.title.trim() : '';
63
+ const snippet = typeof result.snippet === 'string' ? result.snippet.trim() : '';
64
+ if (url.protocol !== 'https:' || !title) return [];
65
+ const found = { title, url: url.href, snippet, date: typeof result.date === 'string' ? result.date : null };
66
+ return accept(found, url) ? [found] : [];
67
+ })
68
+ .slice(0, num);
69
+ }
70
+
71
+ module.exports = { searchSerper };