@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.
package/README.md CHANGED
@@ -6,8 +6,9 @@ d'agent minimale à tool-calling. Dépend de `@astratra/core`.
6
6
  Ce package ne fournit volontairement aucun catalogue de modèles, aucun SDK
7
7
  provider, aucun outil métier — tout ça vient du projet consommateur. Ce
8
8
  qu'il fournit, c'est le mécanisme durement acquis : suivi de quota, ordre de
9
- fallback, cooldown/dégradation, et une petite boucle d'orchestration
10
- d'agent.
9
+ fallback, cooldown/dégradation, deux adaptateurs HTTP sans dépendance (le
10
+ format OpenAI et Gemini), et deux boucles d'agent (protocole écrit, ou
11
+ appels d'outils natifs).
11
12
 
12
13
  ## Routeur de providers
13
14
 
@@ -43,6 +44,129 @@ continue avec des compteurs RAM locaux : ce repli ne peut pas garantir un
43
44
  quota distribué. Les compteurs journaliers se réinitialisent automatiquement
44
45
  à minuit.
45
46
 
47
+ ### L'ordre d'une demande, et qui a répondu
48
+
49
+ Un même projet a souvent plusieurs ordres pour les mêmes modèles : le plus
50
+ rapide d'abord pour ce que la personne attend, le plus capable d'abord pour
51
+ le reste, ceux qui voient seulement pour une photo. `route` dit en plus qui a
52
+ répondu (pour les journaux).
53
+
54
+ ```js
55
+ const router = createProviderRouter({
56
+ providers,
57
+ cooldownMs: 120_000,
58
+ cooldownJitterMs: 0,
59
+ // Ce qui met au repos : un 429 par défaut ; ici aussi un 503 et un délai dépassé.
60
+ cooldownOn: (error) => [429, 503].includes(error.statusCode) || error.name === 'TimeoutError',
61
+ // Tous au repos ? On les essaie quand même : un repos est une supposition.
62
+ whenAllCooling: 'try'
63
+ });
64
+
65
+ const { value, key, partial } = await router.route(requete, {
66
+ candidates: [{ provider: 'groq', model: 'qwen/qwen3.8-27b', extra: { reasoning_format: 'hidden' } }, { provider: 'gemini', model: 'gemini-3.6-flash' }],
67
+ select: (model, provider) => provider.id === 'gemini' || model.vision === true, // une photo : ceux qui voient
68
+ accepts: (reponse) => Boolean(reponse.text), // refusée : le suivant
69
+ partial: (reponse) => reponse.cut === true // coupée : en dernier recours
70
+ }, { signal, purpose: 'chat' });
71
+ ```
72
+
73
+ - Un fournisseur dont `available(ctx)` est faux (pas de clé) est sauté sans
74
+ bruit ; aucun disponible : `code: 'AI_NO_PROVIDER'`. Aucun qui convienne à
75
+ `select` : `'AI_NO_MATCH'`. Tous essayés : `'AI_UNAVAILABLE'` (AppError 503).
76
+ - Une réponse refusée par `accepts` passe au modèle suivant sans compter comme
77
+ une panne ; une réponse `partial` n'est rendue que si personne ne finit.
78
+ - Une **voie** (`provider.lane(ctx)`) : une clé à part pour un usage, avec son
79
+ propre quota. Elle se repose seule (`"gemini:modèle@news"`) : une clé saturée
80
+ par un travail de fond n'arrête jamais les conversations.
81
+ - `ctx.signal` interrompu : la demande s'arrête net avec la raison de
82
+ l'appelant, aucun modèle suivant n'est demandé et aucun ne se repose.
83
+ - `now` injecte l'horloge des repos ; `reset()` les oublie. Le minuteur de
84
+ minuit ne garde jamais le processus en vie.
85
+
86
+ ### Les adaptateurs : format OpenAI et Gemini
87
+
88
+ ```js
89
+ const { createGeminiProvider, createOpenAICompatibleProvider } = require('@astratra/ai');
90
+
91
+ createGeminiProvider({
92
+ getKey: (ctx) => ctx.env[`GEMINI_API_KEY_${ctx.purpose}`] || ctx.env.GEMINI_API_KEY,
93
+ lane: (ctx) => (ctx.env[`GEMINI_API_KEY_${ctx.purpose}`] ? ctx.purpose : null),
94
+ fetch, detailed: true, toRequest: (requete) => requete
95
+ });
96
+ createOpenAICompatibleProvider({
97
+ id: 'cloudflare',
98
+ url: (ctx) => ctx.env.CF_ACCOUNT && `https://api.cloudflare.com/client/v4/accounts/${ctx.env.CF_ACCOUNT}/ai/v1/chat/completions`,
99
+ getKey: (ctx) => ctx.env.CF_TOKEN, fetch, detailed: true, toRequest: (requete) => requete
100
+ });
101
+ ```
102
+
103
+ Les deux prennent la même requête (`{ system, messages, tools, maxTokens }`,
104
+ photos comprises) et rendent la même réponse : `detailed: true` rend
105
+ `{ text, toolCalls, cut }` au routeur, qui juge. La clé et l'adresse sont
106
+ relues à chaque appel (`ctx`) ; `ctx.fetch` et `ctx.timeoutMs` valent pour un
107
+ appel ; `extra` d'un modèle s'ajoute à celui du fournisseur. Gemma reçoit la
108
+ consigne en tête du premier message ; les parties de réflexion et les balises
109
+ `<think>` (même fermée sans ouverture) ne sont jamais montrées ; un appel
110
+ d'outil **écrit dans le texte** (façons de Qwen et de Hermes) devient un vrai
111
+ appel — et n'est jamais une réponse à montrer. Des arguments illisibles gardent
112
+ l'appel, marqué `invalid` avec `invalidReason` (`not_json`, `not_object`), et
113
+ repartent en `{}` au tour suivant.
114
+
115
+ ## Outils natifs : la boucle d'un agent qui appelle ses outils
116
+
117
+ ```js
118
+ const { createToolCaller, runToolLoop, toolSpecs, validateNativeTools } = require('@astratra/ai');
119
+
120
+ const outils = validateNativeTools(catalogue, { requireSummary: true }); // au démarrage
121
+ const appeler = createToolCaller({
122
+ tools: outils, context: { userId }, signal, timeoutMs: 20_000,
123
+ emit: flux.send, // 'step' { id, tool, params } puis 'step_done' { id, ok }
124
+ keep: sources.keep, // createSourceLedger()
125
+ record: async ({ tool, args, found }) => garderAction(tool, args, found), // à confirmer, à annuler
126
+ messages: { waiting: 'Rien n’est écrit : la personne doit confirmer sur son téléphone.' }
127
+ });
128
+ const { text } = await runToolLoop({
129
+ system, messages, tools: toolSpecs(outils), turn, callTool: appeler,
130
+ maxTurns: 6, maxMs: 60_000, finalInstruction: 'Answer now with what you have read: no more tools.', signal
131
+ });
132
+ ```
133
+
134
+ Un outil : `{ name, description, parameters, kind, summary?, run }`, avec
135
+ `perform` pour un outil `confirm` (rien n'est écrit avant qu'un humain
136
+ confirme ; le modèle lit que ça attend) et `undo` pour un outil `write`. Un
137
+ outil qui lève, qui tarde, qu'on invente, ou des arguments illisibles
138
+ deviennent une erreur que le modèle **lit** et corrige au tour suivant ; ce
139
+ qu'un outil rend est borné (`resultMax`, 6 000). Les outils demandés ensemble
140
+ tournent en même temps. À court de tours ou de temps, un dernier tour sans
141
+ outils répond avec ce qui a été lu ; un tour sans texte ni outil lève
142
+ `code: 'AI_NO_ANSWER'`, pour que l'appelant réponde autrement.
143
+ `summary(args)` donne les valeurs de la ligne d'étape (`stepParams`, coupées à
144
+ 120 caractères) : l'interface écrit la phrase, le serveur n'en écrit aucune.
145
+
146
+ ## Le flux vers l'app (server-sent events)
147
+
148
+ ```js
149
+ const flux = openEventStream(res); // Node ou Express
150
+ flux.send('step', { id: 's1', tool: 'read_bible' });
151
+ flux.close();
152
+ flux.signal; // interrompu quand la personne part — pas quand le serveur ferme
153
+ ```
154
+
155
+ Chaque bloc s'écrit `event: <type>\ndata: <json>\n\n`, sans mise en tampon par
156
+ un proxy (`X-Accel-Buffering: no`) ; écrire après la fin ne fait rien.
157
+
158
+ ## Recherche web (Serper)
159
+
160
+ ```js
161
+ const resultats = await searchSerper({ query, sites: ['jw.org'], hl: 'fr' }, {
162
+ key: process.env.SERPER_API_KEY, fetch,
163
+ accept: (resultat, url) => !estHostile(resultat) // écarté avant que le modèle ne lise
164
+ });
165
+ ```
166
+
167
+ Des résultats https avec un titre, 8 au plus. Sans clé, rien n'est demandé
168
+ (`code: 'WEB_SEARCH_NO_KEY'`) ; une panne porte `'WEB_SEARCH_FAILED'`, jamais la clé.
169
+
46
170
  ## Registre d'outils
47
171
 
48
172
  ```js
@@ -53,6 +177,7 @@ registry.register({
53
177
  name: 'get_patient_record',
54
178
  description: "Récupère le dossier d'un patient par son id",
55
179
  type: 'read',
180
+ risk: 'LOW', // LOW, MEDIUM ou HIGH ; absent = UNKNOWN
56
181
  roles: ['doctor', 'admin'],
57
182
  params: { patientId: 'string' },
58
183
  handler: async ({ patientId }, ctx) => patientStore.findById(patientId)
@@ -98,6 +223,43 @@ comme résultat d'outil) et continue, il peut réagir (expliquer, proposer
98
223
  autre chose, s'arrêter). Omis, chaque outil autorisé s'exécute automatiquement,
99
224
  comme avant.
100
225
 
226
+ ### Garde-fous de la boucle, résultats volumineux et risque
227
+
228
+ Les appels répétés avec le même nom et les mêmes paramètres JSON (l'ordre des
229
+ clés d'objet ne compte pas) reçoivent un rappel aux répétitions 3 et 5, puis
230
+ la boucle s'arrête à 8. Ces seuils se règlent avec `loopGuard`; `onEvent`
231
+ reçoit `tool_loop_warning` ou `tool_loop_stopped`. Le nombre d'étapes par
232
+ défaut reste 5 : l'arrêt à 8 ne joue que si `maxSteps` est réglé à 8 ou plus.
233
+
234
+ ```js
235
+ await runAgentLoop({
236
+ prompt, registry, router, userRole: 'doctor',
237
+ loopGuard: { reminder: 3, firmReminder: 5, stop: 8 },
238
+ spill: { threshold: 12_000 },
239
+ confirmationPolicy: { threshold: 'HIGH' },
240
+ riskAnalyzers: [async (call, ctx, tool) => classifier(call, ctx, tool)],
241
+ pendingActions
242
+ });
243
+ ```
244
+
245
+ Au-dessus du seuil (`spill.threshold`, 12 000 caractères par défaut), le
246
+ résultat complet est écrit dans `spill.store` (stockage mémoire par défaut).
247
+ Le modèle reçoit un extrait et un identifiant, puis peut appeler
248
+ `read_spilled_result` avec `{ id, start, length }` pour lire une tranche. Si
249
+ l'écriture échoue, le contenu est supprimé de la réponse et le modèle reçoit
250
+ `result_storage_failed`. Un stockage injecté expose `set(id, value)` et
251
+ `get(id)`.
252
+
253
+ Les risques possibles sont `LOW`, `MEDIUM`, `HIGH` et `UNKNOWN` (valeur des
254
+ outils sans déclaration). La politique de confirmation est inactive par
255
+ défaut, pour préserver l'exécution existante. Elle accepte `'always'`,
256
+ `'never'` ou `{ threshold: 'MEDIUM' }`; dans ce dernier cas, les risques au
257
+ moins aussi élevés que le seuil, dont `UNKNOWN`, demandent une confirmation.
258
+ Les `riskAnalyzers` reçoivent l'appel, le contexte et l'outil ; le niveau le
259
+ plus élevé entre l'outil et les analyseurs l'emporte. Les appels à confirmer
260
+ sont enregistrés par `pendingActions.propose()` et attendent l'approbation
261
+ via le cycle de vie déjà fourni par `createPendingActions`.
262
+
101
263
  **Périmètre V0 — toujours volontairement exclu :** gestion d'images/vision.
102
264
  Fonctionnalité non triviale dont une boucle d'agent de production a besoin,
103
265
  mais dont le portage fidèle reste jugé trop ambitieux pour ce package. À
@@ -201,10 +363,12 @@ const lignes = buildPassagesContext({
201
363
 
202
364
  ## Le texte de la réponse
203
365
 
204
- `tidyMarkdown` ramène la réponse au Markdown qu'un téléphone dessine,
205
- `plainText` l'enlève pour une voix, et `verifyQuotations(texte, { findReferences,
206
- resolve })` remplace une citation infidèle suivie de sa référence par le vrai
207
- texte — ce qu'est une référence et où vit son texte t'appartient.
366
+ `tidyMarkdown` ramène la réponse au Markdown qu'un téléphone dessine (avec
367
+ `remove`, des expressions que l'app ne montre jamais), `plainText` l'enlève
368
+ pour une voix, `wholeSentences` ramène un texte coupé à sa dernière phrase
369
+ entière, et `verifyQuotations(texte, { findReferences, resolve })` remplace une
370
+ citation infidèle suivie de sa référence par le vrai texte — ce qu'est une
371
+ référence et où vit son texte t'appartient.
208
372
 
209
373
  ## La langue de la réponse, la cadence, les points compatibles OpenAI
210
374
 
@@ -213,7 +377,8 @@ texte — ce qu'est une référence et où vit son texte t'appartient.
213
377
  seulement au-dessus d'un seuil — bien plus haut pour deux mots.
214
378
  - `createAskLimit({ max, windowMs, code })` : fenêtre glissante par personne ;
215
379
  le refus porte un code et l'attente, jamais une phrase ; les comptes qui
216
- n'écrivent plus sont oubliés.
380
+ n'écrivent plus sont oubliés (toutes les 500 demandes, et dès qu'une fenêtre
381
+ est passée depuis le dernier nettoyage).
217
382
  - `createOpenAICompatibleProvider({ id, url, getKey, models, fetch })` : un
218
383
  fournisseur pour le routeur. La clé est relue à chaque appel, une erreur porte
219
384
  le statut HTTP (429 → refroidissement) et jamais la clé, des arguments d'outil
@@ -236,6 +401,77 @@ Le modèle lit un code, jamais le message d'erreur. À court de tours ou de
236
401
  temps, un dernier tour sans outils répond avec ce qui a été lu, plutôt qu'une
237
402
  erreur.
238
403
 
404
+ ## llama.cpp : un modèle sur CPU, sur ton VPS
405
+
406
+ Fournisseur « **llama.cpp server** » : un modèle qui tourne sur **CPU** (un VPS
407
+ sans GPU) derrière l'API compatible OpenAI de `llama-server`. Aucune dépendance
408
+ (`src/llamaCpp.js`). C'est un client ; il ne lance rien. Le serveur se lance avec
409
+ le `docker-compose` de `deploy/llama-cpp/`. Ce n'est pas un doublon de
410
+ `createOpenAICompatibleProvider` : celui-ci branche un modèle dans le routeur et
411
+ rend `{ status }` pour une erreur HTTP, alors qu'un serveur hébergé par toi a
412
+ besoin de sa santé, du chargement du modèle (503) et d'erreurs typées.
413
+
414
+ ### Client
415
+
416
+ ```js
417
+ const { createLlamaCppProvider } = require('@astratra/ai');
418
+
419
+ const llm = createLlamaCppProvider({
420
+ baseUrl: 'http://127.0.0.1:8080', // avec ou sans /v1
421
+ apiKey: process.env.LLAMA_API_KEY,
422
+ model: 'local', // l'alias donné au serveur (facultatif)
423
+ timeoutMs: 120_000,
424
+ });
425
+
426
+ await llm.waitUntilReady({ timeoutMs: 120_000 }); // le chargement du modèle prend du temps
427
+ console.log(await llm.health()); // { ok, status: 'ok'|'loading'|'unauthorized'|'error'|'unreachable'|'timeout', latencyMs }
428
+ console.log(await llm.listModels()); // [{ id: 'local', ownedBy: 'llamacpp' }]
429
+
430
+ const { text, usage } = await llm.chat([{ role: 'user', content: 'Bonjour' }], { temperature: 0.2 });
431
+ for await (const piece of llm.chatStream([{ role: 'user', content: 'Raconte-moi une histoire' }])) process.stdout.write(piece);
432
+
433
+ llm.toOpenAICompatible(); // { baseURL: '…/v1', apiKey, model } pour tout autre client compatible OpenAI
434
+ ```
435
+
436
+ `health()` ne lance jamais d'exception (c'est une sonde). Les autres appels
437
+ lancent `LocalLlmError` avec `code` : `UNREACHABLE`, `TIMEOUT`, `UNAUTHORIZED`,
438
+ `LOADING` (503, modèle pas chargé), `HTTP_ERROR` (avec `status`), `INVALID_RESPONSE`.
439
+
440
+ ### Lancer `llama-server` sur un VPS CPU
441
+
442
+ Image officielle : `ghcr.io/ggml-org/llama.cpp:server` (CPU ; épingle un tag
443
+ `server-b<numéro>` en production).
444
+
445
+ ```bash
446
+ cd packages/ai/deploy/llama-cpp
447
+ cp .env.example .env # remplis LLAMA_API_KEY (longue valeur aléatoire) et LLAMA_MODEL_FILE
448
+ mkdir -p models # y déposer le fichier .gguf (quantisation Q4_K_M : bon compromis)
449
+ docker compose up -d
450
+ docker compose logs -f llama # attendre « server is listening »
451
+ curl -H "Authorization: Bearer $LLAMA_API_KEY" http://127.0.0.1:8080/v1/models
452
+ ```
453
+
454
+ Points à régler :
455
+
456
+ - **`LLAMA_THREADS`** : cœurs *physiques*, pas vCPU. Trop de fils ralentit.
457
+ - **`LLAMA_PARALLEL`** : requêtes simultanées. Le contexte (`LLAMA_CTX`) est
458
+ **partagé** : chacune dispose de `LLAMA_CTX / LLAMA_PARALLEL` jetons.
459
+ - **Mémoire** : prévoir la taille du fichier .gguf + ~1 à 2 Go pour le contexte ;
460
+ `LLAMA_MEMORY_LIMIT` plafonne le conteneur.
461
+ - **Débit** : sur CPU, un modèle de 3 à 4 milliards de paramètres en Q4 donne de
462
+ l'ordre de quelques à une dizaine de jetons par seconde selon le VPS ; à
463
+ mesurer sur le tien avant de promettre quoi que ce soit.
464
+ - Le port n'est publié que sur `127.0.0.1` : l'ouverture au public passe par un
465
+ proxy avec TLS, et la clé API reste obligatoire.
466
+ - La clé est lue dans l'environnement (`LLAMA_API_KEY`), jamais en argument.
467
+
468
+ ### Limites
469
+
470
+ Pas de répartition de charge ni de repli intégrés au client : pour router ce
471
+ serveur avec les autres fournisseurs, donne `toOpenAICompatible()` (adresse et clé)
472
+ à `createOpenAICompatibleProvider`. Testé avec un faux
473
+ serveur HTTP ; le vrai `llama-server` n'a pas été lancé dans ce dépôt.
474
+
239
475
  ## Tests
240
476
 
241
477
  ```bash
@@ -0,0 +1,10 @@
1
+ # Copie en .env (jamais commité) puis remplis.
2
+ LLAMA_API_KEY=remplace-par-une-longue-valeur-aleatoire
3
+ LLAMA_MODEL_FILE=nom-du-modele-Q4_K_M.gguf
4
+ LLAMA_ALIAS=local
5
+ LLAMA_CTX=8192
6
+ LLAMA_THREADS=4
7
+ LLAMA_PARALLEL=2
8
+ LLAMA_MEMORY_LIMIT=6g
9
+ LLAMA_MODELS_DIR=./models
10
+ LLAMA_PORT=8080
@@ -0,0 +1,47 @@
1
+ # llama.cpp en inférence CPU sur un VPS — API compatible OpenAI sur le port 8080.
2
+ # NE démarre rien tout seul : `docker compose up -d` après avoir lu le README du paquet.
3
+ #
4
+ # Image officielle : ghcr.io/ggml-org/llama.cpp:server (CPU). Épingle un tag
5
+ # `server-b<numéro>` en production plutôt que le tag flottant.
6
+ services:
7
+ llama:
8
+ image: ${LLAMA_IMAGE:-ghcr.io/ggml-org/llama.cpp:server}
9
+ restart: unless-stopped
10
+ # Écoute en local seulement : la sortie publique passe par un proxy avec TLS (nginx, Caddy).
11
+ ports:
12
+ - "127.0.0.1:${LLAMA_PORT:-8080}:8080"
13
+ volumes:
14
+ # Les fichiers .gguf, à télécharger une fois (voir README).
15
+ - ${LLAMA_MODELS_DIR:-./models}:/models:ro
16
+ environment:
17
+ # La clé est lue dans l'environnement, jamais passée en argument (visible dans `ps`).
18
+ LLAMA_API_KEY: ${LLAMA_API_KEY:?définis LLAMA_API_KEY dans .env}
19
+ command:
20
+ - --host
21
+ - 0.0.0.0
22
+ - --port
23
+ - "8080"
24
+ - --model
25
+ - /models/${LLAMA_MODEL_FILE:?définis LLAMA_MODEL_FILE dans .env}
26
+ - --alias
27
+ - ${LLAMA_ALIAS:-local}
28
+ - --ctx-size
29
+ - "${LLAMA_CTX:-8192}"
30
+ # Fils de calcul : le nombre de cœurs PHYSIQUES, pas de vCPU.
31
+ - --threads
32
+ - "${LLAMA_THREADS:-4}"
33
+ # Requêtes simultanées ; le contexte est partagé entre elles (ctx-size / parallel chacune).
34
+ - --parallel
35
+ - "${LLAMA_PARALLEL:-2}"
36
+ - --metrics
37
+ healthcheck:
38
+ test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
39
+ interval: 30s
40
+ timeout: 5s
41
+ retries: 5
42
+ # Le chargement d'un modèle de plusieurs Go prend du temps.
43
+ start_period: 120s
44
+ deploy:
45
+ resources:
46
+ limits:
47
+ memory: ${LLAMA_MEMORY_LIMIT:-6g}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.4.0",
3
+ "version": "1.6.0",
4
4
  "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
5
5
  "engines": {
6
6
  "node": ">=20"
@@ -9,7 +9,8 @@
9
9
  "types": "src/index.d.ts",
10
10
  "type": "commonjs",
11
11
  "files": [
12
- "src"
12
+ "src",
13
+ "deploy"
13
14
  ],
14
15
  "scripts": {
15
16
  "test": "jest"
@@ -22,7 +23,9 @@
22
23
  "keywords": [
23
24
  "astratra",
24
25
  "ai",
25
- "agents"
26
+ "agents",
27
+ "llama.cpp",
28
+ "cpu-inference"
26
29
  ],
27
30
  "license": "MIT",
28
31
  "publishConfig": {
@@ -40,7 +43,7 @@
40
43
  }
41
44
  },
42
45
  "devDependencies": {
43
- "@astratra/resilience": "^0.2.0",
46
+ "@astratra/resilience": "^1.0.0",
44
47
  "jest": "30.4.2",
45
48
  "redis": "^4.7.0"
46
49
  }
package/src/agentLoop.js CHANGED
@@ -1,6 +1,9 @@
1
1
  const { AppError } = require('@astratra/core');
2
2
 
3
3
  const DEFAULT_MAX_STEPS = 5;
4
+ const DEFAULT_LOOP_THRESHOLDS = Object.freeze({ reminder: 3, firmReminder: 5, stop: 8 });
5
+ const DEFAULT_SPILL_THRESHOLD = 12_000;
6
+ const SPILL_TOOL_NAME = 'read_spilled_result';
4
7
 
5
8
  async function runAgentLoop({
6
9
  prompt,
@@ -17,6 +20,12 @@ async function runAgentLoop({
17
20
  toolTimeoutMs,
18
21
  maxMs,
19
22
  finalInstruction,
23
+ loopGuard = {},
24
+ spill = {},
25
+ confirmationPolicy,
26
+ riskAnalyzers = [],
27
+ pendingActions,
28
+ onEvent,
20
29
  now = Date.now
21
30
  }) {
22
31
  if (!registry) throw new AppError('agentLoop requires a registry', 500);
@@ -26,6 +35,12 @@ async function runAgentLoop({
26
35
  }
27
36
 
28
37
  const messages = Array.isArray(history) ? [...history] : [];
38
+ const loopCounts = new Map();
39
+ const spillStore = spill.store || createMemorySpillStore();
40
+ const spillThreshold = Number.isFinite(spill.threshold) && spill.threshold >= 0 ? spill.threshold : DEFAULT_SPILL_THRESHOLD;
41
+ const thresholds = { ...DEFAULT_LOOP_THRESHOLDS, ...loopGuard };
42
+ const spills = new Map();
43
+ if (typeof spillStore.set !== 'function' || typeof spillStore.get !== 'function') throw new AppError('spill.store requires set() and get()', 500);
29
44
  messages.push({ role: 'user', content: prompt });
30
45
  const started = now();
31
46
 
@@ -53,13 +68,28 @@ async function runAgentLoop({
53
68
  const outOfTime = () => Number.isFinite(maxMs) && now() - started >= maxMs;
54
69
 
55
70
  for (let step = 0; step < maxSteps && !outOfTime(); step += 1) {
56
- const response = await askModel(buildPrompt(registry, userRole, messages));
71
+ const spillInstruction = spills.size ? `\n### Lire un résultat mis de côté\nAppelle <tool_call name="${SPILL_TOOL_NAME}">{"id":"référence","start":0,"length":4000}</tool_call> pour relire une tranche.` : '';
72
+ const response = await askModel(buildPrompt(registry, userRole, messages) + spillInstruction);
57
73
  const toolCall = parseToolCall(response);
58
74
 
59
75
  if (!toolCall) {
60
76
  return response;
61
77
  }
62
78
 
79
+ if (toolCall.name === SPILL_TOOL_NAME) {
80
+ const id = String(toolCall.params.id || '');
81
+ const stored = spills.get(id);
82
+ let result;
83
+ if (!stored) result = { error: 'spill_not_found' };
84
+ else {
85
+ const start = Math.max(0, Math.floor(Number(toolCall.params.start) || 0));
86
+ const length = Math.min(12_000, Math.max(0, Math.floor(Number(toolCall.params.length) || 4000)));
87
+ const value = await spillStore.get(id);
88
+ result = typeof value === 'string' ? { id, start, totalLength: value.length, text: value.slice(start, start + length) } : { error: 'spill_not_found' };
89
+ }
90
+ messages.push({ role: 'assistant', content: response }, { role: 'tool', content: `<tool_result name="${SPILL_TOOL_NAME}">${JSON.stringify(result)}</tool_result>` });
91
+ continue;
92
+ }
63
93
  const tool = registry.getToolByName(toolCall.name);
64
94
  if (!tool) {
65
95
  throw new AppError(`Tool "${toolCall.name}" is not registered`, 400);
@@ -73,8 +103,41 @@ async function runAgentLoop({
73
103
  // runs. Denying doesn't crash the loop: the model gets told and can
74
104
  // adjust course (ask something else, explain, stop), same as it would
75
105
  // handle any other tool result.
76
- if (typeof confirmTool === 'function') {
77
- const approved = await confirmTool(toolCall, ctx);
106
+ const normalizedCall = `${tool.name}:${stableStringify(toolCall.params)}`;
107
+ const repetitions = (loopCounts.get(normalizedCall) || 0) + 1;
108
+ loopCounts.set(normalizedCall, repetitions);
109
+ if (repetitions >= thresholds.stop) {
110
+ const reason = `Boucle arrêtée : l'appel ${tool.name} a été répété ${repetitions} fois.`;
111
+ const event = { type: 'tool_loop_stopped', name: tool.name, repetitions, reason };
112
+ if (typeof onEvent === 'function') onEvent(event);
113
+ return reason;
114
+ }
115
+ if (repetitions === thresholds.reminder || repetitions === thresholds.firmReminder) {
116
+ const reminder = repetitions === thresholds.reminder
117
+ ? `Rappel : cet appel identique a déjà été effectué ${repetitions} fois. Change de stratégie si le résultat ne suffit pas.`
118
+ : `Rappel ferme : cet appel identique a déjà été effectué ${repetitions} fois. Ne le répète plus sans modifier les arguments.`;
119
+ messages.push({ role: 'system', content: reminder });
120
+ if (typeof onEvent === 'function') onEvent({ type: 'tool_loop_warning', name: tool.name, repetitions, message: reminder });
121
+ }
122
+
123
+ let requiresConfirmation = typeof confirmTool === 'function';
124
+ if (confirmationPolicy !== undefined) {
125
+ let risk = tool.risk || 'UNKNOWN';
126
+ for (const analyze of riskAnalyzers) {
127
+ const analyzed = await analyze(toolCall, ctx, tool);
128
+ if (analyzed !== undefined && riskValue(analyzed) > riskValue(risk)) risk = String(analyzed).toUpperCase();
129
+ }
130
+ requiresConfirmation = shouldConfirm(confirmationPolicy, risk);
131
+ }
132
+ if (requiresConfirmation) {
133
+ let approved;
134
+ if (typeof confirmTool === 'function') approved = await confirmTool(toolCall, ctx);
135
+ else if (pendingActions && typeof pendingActions.propose === 'function') {
136
+ const proposed = await pendingActions.propose({ action: tool.name, payload: toolCall.params, description: `Appel ${tool.name} (${tool.risk || 'UNKNOWN'})`, proposedBy: ctx.userId, tenant: ctx.tenantId });
137
+ approved = false;
138
+ messages.push({ role: 'assistant', content: response }, { role: 'tool', content: `<tool_result name="${tool.name}">${JSON.stringify({ pending: true, actionId: proposed.action.id })}</tool_result>` });
139
+ continue;
140
+ } else approved = false;
78
141
  if (!approved) {
79
142
  messages.push({ role: 'assistant', content: response });
80
143
  messages.push({
@@ -100,13 +163,25 @@ async function runAgentLoop({
100
163
  }
101
164
  if (masker && tool.external === true) result = masker.unmaskDeep(result);
102
165
  const serialized = JSON.stringify(result);
166
+ const modelSerialized = masker ? masker.mask(serialized) : serialized;
103
167
  /* Your own data (a class list, a file) carries names the register may not
104
168
  know: the detector reads the result before it can reach the prompt. */
105
169
  if (masker && tool.external !== true && typeof masker.maskAsync === 'function') await masker.maskAsync(String(serialized));
106
170
  messages.push({ role: 'assistant', content: response });
171
+ let modelResult = serialized;
172
+ if (serialized.length > spillThreshold) {
173
+ const id = createSpillId();
174
+ try {
175
+ await spillStore.set(id, serialized);
176
+ spills.set(id, true);
177
+ modelResult = JSON.stringify({ spilled: true, id, totalLength: serialized.length, excerpt: modelSerialized.slice(0, 1500), readTool: SPILL_TOOL_NAME });
178
+ } catch (_error) {
179
+ modelResult = JSON.stringify({ error: 'result_storage_failed' });
180
+ }
181
+ }
107
182
  messages.push({
108
183
  role: 'tool',
109
- content: `<tool_result name="${tool.name}">${serialized}</tool_result>`
184
+ content: `<tool_result name="${tool.name}">${modelResult}</tool_result>`
110
185
  });
111
186
  }
112
187
 
@@ -121,6 +196,24 @@ async function runAgentLoop({
121
196
  throw new AppError(`agentLoop reached maxSteps (${maxSteps}) before a final answer`, 500);
122
197
  }
123
198
 
199
+ function stableStringify(value) {
200
+ if (value === null || typeof value !== 'object') return JSON.stringify(value);
201
+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
202
+ return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
203
+ }
204
+ function riskValue(risk) { return ({ LOW: 0, MEDIUM: 1, HIGH: 2, UNKNOWN: 3 })[String(risk).toUpperCase()] ?? 3; }
205
+ function shouldConfirm(policy, risk) {
206
+ if (policy === 'always') return true;
207
+ if (policy === 'never') return false;
208
+ const threshold = typeof policy === 'object' && policy ? policy.threshold : policy;
209
+ return risk === 'UNKNOWN' || riskValue(risk) >= riskValue(threshold);
210
+ }
211
+ function createMemorySpillStore() {
212
+ const values = new Map();
213
+ return { async set(id, value) { values.set(id, value); }, async get(id) { return values.get(id); } };
214
+ }
215
+ function createSpillId() { return `spill_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`; }
216
+
124
217
  async function runTool(tool, params, ctx, timeoutMs) {
125
218
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return tool.handler(params, ctx);
126
219
  let timer;
@@ -200,5 +293,8 @@ function estimateTokens(text) {
200
293
  }
201
294
 
202
295
  module.exports = {
203
- runAgentLoop
296
+ runAgentLoop,
297
+ createMemorySpillStore,
298
+ DEFAULT_LOOP_THRESHOLDS,
299
+ DEFAULT_SPILL_THRESHOLD
204
300
  };
package/src/answerText.js CHANGED
@@ -33,6 +33,8 @@ function plainText(text) {
33
33
  * @param {string} text
34
34
  * @param {object} [options]
35
35
  * @param {boolean} [options.removeEmoji] drop emoji — for an app that draws its own symbols. Default false.
36
+ * @param {RegExp[]} [options.remove] ce que l'app ne montre jamais, retiré après les marques
37
+ * (des lettres d'un autre alphabet recopiées d'un titre, par exemple). Chaque expression est globale.
36
38
  */
37
39
  function tidyMarkdown(text, options = {}) {
38
40
  let out = String(text === null || text === undefined ? '' : text)
@@ -49,6 +51,10 @@ function tidyMarkdown(text, options = {}) {
49
51
  .replace(/(^|[^*])\*(?!\*)/g, '$1')
50
52
  .replace(/`([^`]+)`/g, '$1')
51
53
  .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1');
54
+ for (const pattern of options.remove || []) {
55
+ if (!(pattern instanceof RegExp) || !pattern.global) throw new Error('tidyMarkdown: every options.remove entry must be a global RegExp.');
56
+ out = out.replace(pattern, '');
57
+ }
52
58
  if (options.removeEmoji) {
53
59
  out = out.replace(/[\p{Extended_Pictographic}\p{Emoji_Modifier}\u{FE0F}\u{200D}]/gu, '');
54
60
  }
@@ -59,6 +65,20 @@ function tidyMarkdown(text, options = {}) {
59
65
  .trim();
60
66
  }
61
67
 
68
+ /**
69
+ * Un texte coupé à sa longueur, ramené à sa dernière phrase entière : jamais
70
+ * un mot coupé en deux. Sans fin de phrase, le texte reste tel quel.
71
+ * @param {string} text
72
+ * @param {object} [options]
73
+ * @param {string[]} [options.marks] ce qui termine une phrase. Défaut : . ! ? … » ) "
74
+ */
75
+ function wholeSentences(text, options = {}) {
76
+ const trimmed = String(text === null || text === undefined ? '' : text).trimEnd();
77
+ const marks = options.marks || ['.', '!', '?', '…', '»', ')', '"'];
78
+ const end = Math.max(...marks.map((mark) => trimmed.lastIndexOf(mark)));
79
+ return end > 0 ? trimmed.slice(0, end + 1) : trimmed;
80
+ }
81
+
62
82
  /* A quotation between guillemets, curly quotes or straight quotes. */
63
83
  const QUOTATION = /(«\s*)([^«»]+?)(\s*»)|(“)([^“”]+)(”)|(")([^"\n]+)(")/g;
64
84
  /* What may stand between a quotation and the reference saying where it comes from. */
@@ -114,4 +134,4 @@ async function verifyQuotations(text, options = {}) {
114
134
  return out;
115
135
  }
116
136
 
117
- module.exports = { plainText, tidyMarkdown, verifyQuotations, isFaithfulQuotation };
137
+ module.exports = { plainText, tidyMarkdown, verifyQuotations, isFaithfulQuotation, wholeSentences };
package/src/askLimit.js CHANGED
@@ -17,6 +17,8 @@ const { AppError } = require('@astratra/core');
17
17
  * @param {number} options.windowMs
18
18
  * @param {string} [options.code] Default 'AI_RATE_LIMITED'.
19
19
  * @param {number} [options.sweepEvery] asks between two clean-ups. Default 500.
20
+ * Une fenêtre passée depuis le dernier nettoyage en déclenche un aussi : un
21
+ * serveur peu sollicité oublie ses comptes inactifs sans attendre 500 demandes.
20
22
  */
21
23
  function createAskLimit(options = {}) {
22
24
  const { max, windowMs } = options;
@@ -26,6 +28,7 @@ function createAskLimit(options = {}) {
26
28
  const sweepEvery = options.sweepEvery || 500;
27
29
  const asks = new Map();
28
30
  let sinceSweep = 0;
31
+ let sweptAt = -Infinity;
29
32
 
30
33
  function sweep(now) {
31
34
  for (const [id, times] of asks) {
@@ -33,6 +36,7 @@ function createAskLimit(options = {}) {
33
36
  if (recent.length) asks.set(id, recent);
34
37
  else asks.delete(id);
35
38
  }
39
+ sweptAt = now;
36
40
  }
37
41
 
38
42
  /** What `take` would answer, without counting an ask. */
@@ -46,7 +50,7 @@ function createAskLimit(options = {}) {
46
50
  function take(subject, now = Date.now()) {
47
51
  const id = String(subject);
48
52
  sinceSweep += 1;
49
- if (sinceSweep >= sweepEvery) {
53
+ if (sinceSweep >= sweepEvery || now - sweptAt >= windowMs) {
50
54
  sinceSweep = 0;
51
55
  sweep(now);
52
56
  }