@astratra/ai 1.12.0 → 1.14.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
@@ -49,6 +49,28 @@ défaut (bloquer et signaler). `failOpen` laisse passer en signalant
49
49
  `degraded` ; `recommendedGuards({ readOnly: true })` l'applique à un agent qui
50
50
  ne fait que lire. Le mode d'une exécution est `newRun({ mode: 'action' | 'read' })`.
51
51
 
52
+ **Textes courts (1.13.0)** : un texte de moins de `injection.minWords` mots (3 par
53
+ défaut ; `0` envoie tout) n'est pas soumis au modèle d'injection, qui note un ou
54
+ deux mots au hasard (mesuré sur Examen d'État le 20/10/2026 : « oui » 0,96,
55
+ « Salut » 0,72, alors que toutes les vraies attaques dépassaient 0,993 dès trois
56
+ mots). Le résultat porte `score: null` et la raison `too_short_to_scan`.
57
+
58
+ **Où passent les messages de la personne** : par `input()`, jamais par
59
+ `toolResult(…, { external: true })`. `toolResult` sert à ce qui vient de
60
+ l'extérieur (page web, fichier, réponse d'un service) ; un message de la
61
+ personne passé par là peut marquer toute l'exécution `requiresConfirmation`, et
62
+ un agent qui revérifie tout l'historique à chaque tour reste alors bloqué.
63
+
64
+ **À savoir avec `recommendedGuards`** :
65
+ - sans `readOnly`, la politique est `failClosed` partout : si le modèle
66
+ d'entités ne répond plus (par exemple son disjoncteur ouvert après des délais
67
+ dépassés quand un tour vérifie beaucoup de messages en parallèle), `input`
68
+ bloque et l'agent entier s'arrête. Pour un agent qui ne fait que lire,
69
+ `readOnly: true` ; sinon, limiter ce qui est revérifié à chaque tour ;
70
+ - l'ancrage (`output.grounding`, NLI phrase par phrase) coûte de l'ordre de 3 s
71
+ par réponse sur un processeur ; c'est un signal, `output: { grounding: false }`
72
+ le coupe quand la latence compte plus.
73
+
52
74
  **Événements** : chaque décision appelle `onEvent({ type: 'guard', guard, decision,
53
75
  reasons, degraded, metrics, runId, mode, at })`. Ils ne contiennent jamais le
54
76
  texte (ni saisie, ni résultat d'outil, ni réponse) : des nombres, des codes et
@@ -78,7 +100,10 @@ suspected, forbids every action without a human for the rest of the run
78
100
  (`beforeAction`), `output` unmasks the reply and checks grounding against the
79
101
  sources, personal-data leaks and moderation. Failure policy is `failClosed` for
80
102
  actions by default, `failOpen` possible for read-only runs. Events never carry
81
- the text. Mocks for tests: `@astratra/ai/guards/testing`.
103
+ the text. Mocks for tests: `@astratra/ai/guards/testing`. Since 1.13.0, texts
104
+ under `injection.minWords` words (default 3) are not sent to the injection
105
+ model, which scores one or two words at random; the person's own messages go
106
+ through `input()`, never `toolResult(…, { external: true })`.
82
107
 
83
108
  ## Routeur de providers
84
109
 
@@ -182,6 +207,12 @@ appel — et n'est jamais une réponse à montrer. Des arguments illisibles gard
182
207
  l'appel, marqué `invalid` avec `invalidReason` (`not_json`, `not_object`), et
183
208
  repartent en `{}` au tour suivant.
184
209
 
210
+ **Schémas d'outils chez Gemini (1.13.0)** : l'API Gemini native refuse
211
+ `additionalProperties`, `$schema` et `$id` dans les paramètres d'une fonction
212
+ (400 « Unknown name "additionalProperties" »). Ils sont retirés à toute
213
+ profondeur avant l'envoi (une *propriété* qui porte un de ces noms reste) ; les
214
+ schémas stricts produits par `toolSpecs` passent donc tels quels.
215
+
185
216
  **Signatures de pensée (Gemini 3, 1.12.0)** : chaque appel d'outil de Gemini 3
186
217
  porte une signature, à rendre telle quelle au tour suivant, sinon Gemini répond
187
218
  400. Elle arrive dans `toolCalls[i].signature` (directement chez Gemini, par
@@ -274,6 +305,29 @@ outils répond avec ce qui a été lu ; un tour sans texte ni outil lève
274
305
  `summary(args)` donne les valeurs de la ligne d'étape (`stepParams`, coupées à
275
306
  120 caractères) : l'interface écrit la phrase, le serveur n'en écrit aucune.
276
307
 
308
+ ## Se brancher sur un serveur MCP
309
+
310
+ `connectMcpServer` relie une IA à un serveur MCP distant (transport « Streamable HTTP ») et rend ses outils au format des outils natifs, prêts pour `runToolLoop` ou `createToolCaller`. Premier usage : Palabre, la salle où les IA parlent entre elles ; un autre serveur MCP se branche de la même façon.
311
+
312
+ ```js
313
+ const { connectMcpServer, runToolLoop } = require('@astratra/ai');
314
+
315
+ const palabre = await connectMcpServer({
316
+ url: 'https://palabre.boutiqueroro.com/mcp',
317
+ headers: { Authorization: `Bearer ${process.env.PALABRE_CLE}` },
318
+ prefix: 'palabre_',
319
+ allow: ['lire_reunion', 'ecrire_message', 'prochaine_reunion', 'retenir_reunion'],
320
+ kinds: { ecrire_message: { kind: 'write', risk: 'LOW' } }
321
+ });
322
+ // palabre.tools s'ajoute aux outils de l'IA ; palabre.instructions donne les règles du serveur.
323
+ await palabre.close();
324
+ ```
325
+
326
+ - Ce que rend un serveur MCP est une donnée non fiable : chaque outil porte `external: true`, pour que les gardes le traitent comme tel.
327
+ - Un outil est « read » par défaut ; l'application déclare ceux qui écrivent (`kinds`), avec leur risque, et leur `undo` si elle le demande.
328
+ - `allow` limite les outils à une liste connue : un outil ajouté plus tard par le serveur n'arrive pas en douce.
329
+ - La clé passe par `headers` ; elle n'est ni journalisée ni rendue.
330
+
277
331
  ## Le flux vers l'app (server-sent events)
278
332
 
279
333
  ```js
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.12.0",
3
+ "version": "1.14.0",
4
4
  "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra, plus agent guards (@astratra/ai/guards): outbound masking, prompt-injection handling for untrusted tool results, reply checks.",
5
5
  "engines": {
6
6
  "node": ">=20"
@@ -28,14 +28,16 @@
28
28
  "llama.cpp",
29
29
  "cpu-inference",
30
30
  "guardrails",
31
- "prompt-injection"
31
+ "prompt-injection",
32
+ "mcp"
32
33
  ],
33
34
  "license": "MIT",
34
35
  "publishConfig": {
35
36
  "access": "public"
36
37
  },
37
38
  "dependencies": {
38
- "@astratra/core": "^1.0.0"
39
+ "@astratra/core": "^1.0.0",
40
+ "@modelcontextprotocol/sdk": "^1.32.1"
39
41
  },
40
42
  "peerDependencies": {
41
43
  "redis": ">=4",
package/src/gemini.js CHANGED
@@ -130,6 +130,24 @@ function readGeminiGrounding(answer) {
130
130
  return { searched: queries.length > 0 || sources.length > 0, queries, sources, searchSuggestionsHtml: entry };
131
131
  }
132
132
 
133
+ /* L'API Gemini native refuse ces mots de JSON Schema dans `parameters` (400 « Unknown name "additionalProperties" »),
134
+ alors que les schémas stricts en portent souvent (`additionalProperties: false`). Ils sont retirés à toute profondeur,
135
+ sans toucher à une propriété qui porte un de ces noms (les clés de `properties` sont des noms, pas des mots du schéma). */
136
+ const GEMINI_UNSUPPORTED = new Set(['additionalProperties', '$schema', '$id']);
137
+ function geminiSchema(value) {
138
+ if (Array.isArray(value)) return value.map(geminiSchema);
139
+ if (!value || typeof value !== 'object') return value;
140
+ const out = {};
141
+ for (const [key, child] of Object.entries(value)) {
142
+ if (GEMINI_UNSUPPORTED.has(key)) continue;
143
+ out[key] = key === 'properties' && child && typeof child === 'object' && !Array.isArray(child)
144
+ ? Object.fromEntries(Object.entries(child).map(([name, schema]) => [name, geminiSchema(schema)]))
145
+ : geminiSchema(child);
146
+ }
147
+ return out;
148
+ }
149
+ const geminiDeclaration = (tool) => (tool && tool.parameters ? { ...tool, parameters: geminiSchema(tool.parameters) } : tool);
150
+
133
151
  /** Le corps de la requête pour un modèle. */
134
152
  function requestBody(model, request, noSystemInstruction, search = null, dropFunctions = false) {
135
153
  const contents = contentsOf(request.messages, model);
@@ -138,7 +156,7 @@ function requestBody(model, request, noSystemInstruction, search = null, dropFun
138
156
  maxOutputTokens: request.maxTokens || 1200
139
157
  };
140
158
  const toolList = [];
141
- if (request.tools && request.tools.length && !dropFunctions) toolList.push({ functionDeclarations: request.tools });
159
+ if (request.tools && request.tools.length && !dropFunctions) toolList.push({ functionDeclarations: request.tools.map(geminiDeclaration) });
142
160
  if (search) toolList.push({ google_search: {} });
143
161
  const functions = toolList.length ? { tools: toolList } : {};
144
162
  const system = request.system || '';
@@ -27,6 +27,9 @@ const FAIL_OPEN = 'failOpen';
27
27
  const DECISIONS = Object.freeze(['allow', 'flag', 'block']);
28
28
  const SEVERITY = { allow: 0, flag: 1, block: 2 };
29
29
  const DEFAULT_MAX_SCAN_CHARS = 100000;
30
+ const DEFAULT_MIN_WORDS = 3;
31
+ /* Words that carry letters or digits: emoji and punctuation alone are not words. */
32
+ const wordCount = (text) => String(text).split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
30
33
  const WITHHELD = '[content withheld by a guard]';
31
34
 
32
35
  const keyHash = (key) => crypto.createHash('sha256').update(String(key)).digest('hex');
@@ -77,7 +80,8 @@ function lazyVerifySources() {
77
80
  * @param {Function} [options.onEvent]
78
81
  * @param {string[]} [options.names] register names always masked.
79
82
  * @param {string[]} [options.entityLabels] default ['person'].
80
- * @param {object} [options.injection] { threshold = 0.5, actionThreshold = threshold, maxScanChars, chunkChars, overlapChars }.
83
+ * @param {object} [options.injection] { threshold = 0.5, actionThreshold = threshold, maxScanChars, chunkChars, overlapChars,
84
+ * minWords = 3 (shorter texts are not sent to the injection model; 0 sends everything) }.
81
85
  * @param {object} [options.output] { grounding = true, leak = true, moderation = true, minSupport = 0.5, leakTypes }.
82
86
  * @param {Function} [options.verifySources] (answer, sources, { nli }) => report; default: @astratra/rag if installed.
83
87
  * @param {'action'|'read'} [options.defaultMode] mode of a run that does not name one. Default 'action'.
@@ -101,6 +105,8 @@ function createGuards(options = {}) {
101
105
  const maxScanChars = injectionOptions.maxScanChars || DEFAULT_MAX_SCAN_CHARS;
102
106
  const chunkChars = injectionOptions.chunkChars || 6000;
103
107
  const overlapChars = injectionOptions.overlapChars === undefined ? 300 : injectionOptions.overlapChars;
108
+ const minWords = injectionOptions.minWords === undefined ? DEFAULT_MIN_WORDS : injectionOptions.minWords;
109
+ if (!Number.isInteger(minWords) || minWords < 0) throw new TypeError('injection.minWords must be an integer >= 0.');
104
110
  const outputOptions = { grounding: true, leak: true, moderation: true, minSupport: 0.5, ...(options.output || {}) };
105
111
  const verifySources = options.verifySources || (outputOptions.grounding ? lazyVerifySources() : null);
106
112
 
@@ -233,6 +239,9 @@ function createGuards(options = {}) {
233
239
  /* ---- toolResult --------------------------------------------------------- */
234
240
 
235
241
  async function scanForInjection(content, threshold) {
242
+ /* One or two words carry no instruction, and the injection model scores them at random (« oui » 0.96,
243
+ « Salut » 0.72 on Examen d'État, 20/10/2026, where every real attack scored ≥ 0.993 from three words up). */
244
+ if (wordCount(content) < minWords) return { score: null, suspected: false, chunks: 0, short: true };
236
245
  const pieces = windowsOf(content, chunkChars, overlapChars);
237
246
  let max = 0;
238
247
  for (let i = 0; i < pieces.length; i += 8) {
@@ -271,7 +280,10 @@ function createGuards(options = {}) {
271
280
  } else {
272
281
  const scan = await scanForInjection(content, run.mode === 'action' ? actionThreshold : injectionThreshold);
273
282
  if (scan.failed) degraded.push('injection');
274
- else ({ score, suspected, chunks } = scan);
283
+ else {
284
+ ({ score, suspected, chunks } = scan);
285
+ if (scan.short) reasons.push('too_short_to_scan');
286
+ }
275
287
  }
276
288
  if (degraded.length) {
277
289
  reasons.push('injection_check_unavailable');
@@ -65,6 +65,8 @@ export interface CreateGuardsOptions {
65
65
  maxScanChars?: number;
66
66
  chunkChars?: number;
67
67
  overlapChars?: number;
68
+ /** Texts with fewer words are not sent to the injection model (it scores one or two words at random). Default 3; 0 sends everything. */
69
+ minWords?: number;
68
70
  };
69
71
  output?: {
70
72
  grounding?: boolean;
package/src/index.d.ts CHANGED
@@ -1162,3 +1162,35 @@ export function createInferenceQueue(options?: { maxConcurrent?: number; maxQueu
1162
1162
  run<T>(task: () => Awaitable<T>, options?: { signal?: AbortSignal }): Promise<T>;
1163
1163
  stats(): { active: number; waiting: number };
1164
1164
  };
1165
+
1166
+ /* ─────────────────── Connecteur MCP ─────────────────── */
1167
+
1168
+ /** Un outil d'un serveur MCP, rendu au format des outils natifs ; son résultat est une donnée non fiable (`external`). */
1169
+ export interface McpNativeTool extends NativeTool {
1170
+ external: true;
1171
+ mcp: { name: string };
1172
+ }
1173
+
1174
+ export interface McpConnection {
1175
+ tools: McpNativeTool[];
1176
+ /** Les instructions annoncées par le serveur, ou null. */
1177
+ instructions: string | null;
1178
+ close(): Promise<void>;
1179
+ }
1180
+
1181
+ /** Se connecte à un serveur MCP (Streamable HTTP) et rend ses outils au format des outils natifs. */
1182
+ export function connectMcpServer(options: {
1183
+ url?: string;
1184
+ headers?: Record<string, string>;
1185
+ prefix?: string;
1186
+ allow?: string[];
1187
+ kinds?: Record<string, NativeToolKind | { kind?: NativeToolKind; risk?: DeclaredToolRisk }>;
1188
+ timeoutMs?: number;
1189
+ resultMax?: number;
1190
+ client?: { name: string; version: string };
1191
+ transport?: unknown;
1192
+ fetch?: typeof globalThis.fetch;
1193
+ }): Promise<McpConnection>;
1194
+
1195
+ /** Le nom d'outil Astratra d'un outil MCP (minuscules, chiffres, « _ », 64 caractères au plus). */
1196
+ export function mcpToolName(prefix: string, name: string): string;
package/src/index.js CHANGED
@@ -27,5 +27,6 @@ module.exports = {
27
27
  ...require('./serviceHttp'),
28
28
  ...require('./serviceLanguage'),
29
29
  ...require('./voice'),
30
- ...require('./providerLimits')
30
+ ...require('./providerLimits'),
31
+ ...require('./mcpClient')
31
32
  };
@@ -0,0 +1,118 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Connecteur MCP (26/10/2026) : une IA d'Astratra se branche sur un serveur MCP distant (transport « Streamable HTTP »)
5
+ * et en reçoit les outils comme ses outils natifs ({ name, description, parameters, kind, run }), prêts pour
6
+ * runToolLoop / createToolCaller. Premier usage : Palabre, la salle où les IA d'Emch parlent entre elles ; tout autre
7
+ * serveur MCP (GitHub, documentation…) se branche de la même façon.
8
+ *
9
+ * Règles :
10
+ * - ce que rend un serveur MCP est une DONNÉE NON FIABLE : chaque outil est marqué `external: true`, pour que les gardes
11
+ * de l'application (prompt-injection) le traitent comme tel ;
12
+ * - un outil est « read » par défaut ; l'application déclare elle-même ceux qui écrivent (`kinds`), avec leur risque ;
13
+ * - `allow` limite les outils exposés à une liste connue : un serveur qui ajoute un outil ne le donne pas à l'IA en douce ;
14
+ * - la clé (en-tête Authorization) n'est jamais journalisée ni rendue.
15
+ */
16
+
17
+ const NAME = /^[a-z][a-z0-9_]{0,63}$/;
18
+ const DEFAULT_RESULT_MAX = 20_000;
19
+ const DEFAULT_TIMEOUT_MS = 20_000;
20
+
21
+ /** Un nom d'outil MCP ramené aux noms d'Astratra (minuscules, chiffres, « _ », 64 caractères au plus). */
22
+ function toolNameOf(prefix, name) {
23
+ const brut = `${prefix || ''}${String(name)}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+/, '');
24
+ const nom = /^[a-z]/.test(brut) ? brut : `mcp_${brut}`;
25
+ return nom.slice(0, 64);
26
+ }
27
+
28
+ /** Le texte d'un résultat MCP : les parties texte jointes ; un JSON valide est rendu comme objet. */
29
+ function resultValue(result, max) {
30
+ const texte = (Array.isArray(result?.content) ? result.content : [])
31
+ .filter((part) => part && part.type === 'text' && typeof part.text === 'string')
32
+ .map((part) => part.text)
33
+ .join('\n')
34
+ .slice(0, max);
35
+ if (result?.structuredContent && typeof result.structuredContent === 'object') return result.structuredContent;
36
+ try { return JSON.parse(texte); } catch { return texte; }
37
+ }
38
+
39
+ async function chargerSdk() {
40
+ const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
41
+ const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
42
+ return { Client, StreamableHTTPClientTransport };
43
+ }
44
+
45
+ /**
46
+ * Se connecte à un serveur MCP et rend ses outils au format des outils natifs.
47
+ *
48
+ * @param {object} options
49
+ * @param {string} options.url adresse du serveur MCP (https://…/mcp)
50
+ * @param {Record<string,string>} [options.headers] en-têtes envoyés à chaque requête (par exemple Authorization: Bearer …)
51
+ * @param {string} [options.prefix] préfixe des noms d'outils (par exemple « palabre_ »)
52
+ * @param {string[]} [options.allow] noms MCP des seuls outils à exposer
53
+ * @param {Record<string,{kind?:string,risk?:string}|string>} [options.kinds] genre et risque par nom MCP (défaut read)
54
+ * @param {number} [options.timeoutMs] délai d'un appel d'outil (défaut 20 s)
55
+ * @param {number} [options.resultMax] taille maximale du texte rendu (défaut 20 000)
56
+ * @param {{name:string,version:string}} [options.client] identité du client annoncée au serveur
57
+ * @param {object} [options.transport] transport MCP déjà construit (tests) ; sinon Streamable HTTP
58
+ * @param {Function} [options.fetch] fetch utilisé par le transport
59
+ * @returns {Promise<{ tools: object[], instructions: string|null, close(): Promise<void> }>}
60
+ */
61
+ async function connectMcpServer(options = {}) {
62
+ const { url, headers = {}, prefix = '', allow = null, kinds = {}, timeoutMs = DEFAULT_TIMEOUT_MS, resultMax = DEFAULT_RESULT_MAX } = options;
63
+ if (!options.transport && !url) throw new Error('connectMcpServer: url is required');
64
+ const { Client, StreamableHTTPClientTransport } = await chargerSdk();
65
+ const transport = options.transport || new StreamableHTTPClientTransport(new URL(url), {
66
+ requestInit: { headers },
67
+ ...(options.fetch ? { fetch: options.fetch } : {})
68
+ });
69
+ const client = new Client(options.client || { name: 'astratra-ai', version: '1.0.0' });
70
+ await client.connect(transport);
71
+
72
+ const decrits = [];
73
+ let curseur;
74
+ do {
75
+ const page = await client.listTools(curseur ? { cursor: curseur } : {});
76
+ decrits.push(...(page.tools || []));
77
+ curseur = page.nextCursor;
78
+ } while (curseur);
79
+
80
+ const permis = allow ? new Set(allow) : null;
81
+ const tools = decrits
82
+ .filter((t) => !permis || permis.has(t.name))
83
+ .map((t) => {
84
+ const name = toolNameOf(prefix, t.name);
85
+ if (!NAME.test(name)) return null;
86
+ const reglage = typeof kinds[t.name] === 'string' ? { kind: kinds[t.name] } : (kinds[t.name] || {});
87
+ const parameters = t.inputSchema && t.inputSchema.type === 'object' ? t.inputSchema : { type: 'object', properties: {} };
88
+ return {
89
+ name,
90
+ description: String(t.description || t.title || t.name).slice(0, 2000),
91
+ parameters,
92
+ kind: reglage.kind || 'read',
93
+ ...(reglage.risk ? { risk: reglage.risk } : {}),
94
+ external: true,
95
+ mcp: { name: t.name },
96
+ summary: () => ({}),
97
+ async run(args, ctx = {}) {
98
+ const result = await client.callTool({ name: t.name, arguments: args || {} }, undefined, {
99
+ timeout: timeoutMs,
100
+ ...(ctx.signal ? { signal: ctx.signal } : {})
101
+ });
102
+ const data = resultValue(result, resultMax);
103
+ if (result && result.isError) return { data: { erreur: true, detail: data } };
104
+ return { data };
105
+ }
106
+ };
107
+ })
108
+ .filter(Boolean);
109
+
110
+ const instructions = typeof client.getInstructions === 'function' ? (client.getInstructions() || null) : null;
111
+ return {
112
+ tools,
113
+ instructions,
114
+ async close() { await client.close().catch(() => {}); }
115
+ };
116
+ }
117
+
118
+ module.exports = { connectMcpServer, mcpToolName: toolNameOf };