@nodefony/ai 0.0.0-stage → 10.0.0-beta.4

package/dist/nodefony/mcp/tools.js

@@ -0,0 +1,485 @@
+import { missingScopes, rolesFromScopes } from "nodefony";
+// nodefony/mcp/tools.ts
+/**
+* Outils MCP : la **collecte** de ceux qu'une application déclare, leur
+* publication et leur exécution — la part générique de toute porte MCP.
+*
+* Les CONTRATS (`IMcpTool` et ses voisins) vivent au cœur, parce qu'un module
+* les implémente par {@link IModule.getMcpTools} sans dépendre d'aucune porte ;
+* la MÉCANIQUE vit ici. Le catalogue `nodefony_*` n'est pas ici non plus : il
+* appartient à `@nodefony/devkit`, qui le déclare comme n'importe quel module.
+*
+* ## Pourquoi la collecte, et pas un registre
+*
+* Un module déclare ses outils par {@link IModule.getMcpTools} ; ils sont
+* ramassés **au moment de servir la requête**, jamais stockés. C'est
+* délibérément l'inverse du data plane admin ({@link IAdminRegistry}), qui a
+* besoin d'un registre parce qu'il monte des ROUTES au boot et qu'un module
+* arrivé trop tard n'aurait plus rien à monter. Un outil MCP n'a rien à monter :
+* il est lu à la demande. D'où trois propriétés gagnées gratuitement — aucune
+* structure allouée au démarrage (donc coût nul en production, où aucune porte
+* MCP n'existe), aucun ordre de `register()` à respecter, et une fraîcheur qui
+* est une propriété du mécanisme plutôt qu'une discipline à tenir.
+*/
+/**
+* Au-delà de quoi une réponse cesse d'être une réponse.
+*
+* Mesuré, pas choisi en l'air : `inspect routes` rendait 47 000 caractères et
+* `inspect config` 190 730 — le second dépassait ce que le client accepte, il
+* partait sur disque, et l'agent brûlait vingt tours à le relire au `jq`. Le
+* premier passait, et ne servait à rien pour autant : à qui demandait le NOMBRE
+* de routes, il fallait compter 119 objets dans un mur de JSON.
+*
+* La borne est donc largement SOUS la limite des clients : ce qu'on protège
+* n'est pas le transport, c'est la capacité de l'agent à répondre sans relire.
+*/
+const MCP_TEXT_MAX_CHARS = 32e3;
+/** Ce qu'on garde d'une valeur dans une vue d'ensemble : la surface. */
+const SCALAR_MAX_CHARS = 120;
+/**
+* La SURFACE d'un objet — ses champs scalaires courts, sans sa profondeur.
+*
+* Ce qui pèse dans un inventaire n'est presque jamais ce qu'on y cherche : sur
+* une route, `name`/`path`/`controller` tiennent en cent caractères, et c'est la
+* description, les tableaux de tags et les objets imbriqués qui font les 47 ko.
+* On jette donc la profondeur et on garde la surface — TOUTES les entrées
+* restent visibles, ce qu'un échantillon des N premières ne permet pas : une
+* question portant sur la 100ᵉ recevrait une réponse fausse, et l'agent n'aurait
+* aucun moyen de le savoir.
+*/
+function surfaceOf(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return `[${value.length}]`;
+	const kept = {};
+	for (const [key, v] of Object.entries(value)) if (v === null || typeof v === "number" || typeof v === "boolean") kept[key] = v;
+	else if (typeof v === "string" && v.length <= SCALAR_MAX_CHARS) kept[key] = v;
+	else if (Array.isArray(v) && v.every((e) => typeof e === "string")) {
+		if (v.join(",").length <= SCALAR_MAX_CHARS) kept[key] = v;
+	}
+	return kept;
+}
+/**
+* Une donnée trop volumineuse, ramenée à une RÉPONSE.
+*
+* Deux formes, selon ce qu'on a sous la main :
+*  - **un tableau** rend son `count` — la première chose qu'on veut d'une liste,
+*    et celle qu'un modèle calcule mal et cher — puis ses entrées en surface ;
+*  - **un objet** rend ses clés de premier niveau : c'est la carte qui permet de
+*    demander ensuite la bonne branche (pour `config`, `inspect module <nom>`).
+*
+* Dans les deux cas la réponse DIT ce qu'elle a fait, et elle le dit EN TÊTE.
+* Une troncature muette est pire que pas de troncature — l'agent croit tout
+* tenir ; une troncature annoncée APRÈS vingt mille caractères d'entrées ne vaut
+* guère mieux, il a déjà décidé quoi faire de ce qu'il a lu. Mesuré : sur la
+* tâche « annonce le nombre de routes », l'agent recevait `count` puis 88
+* entrées puis, tout en bas, l'avertissement — et repartait recompter les
+* entrées visibles au lieu de lire le compte exact qu'on venait de lui donner.
+*
+* Et la note ne renvoie PAS vers un affinement : `routes`, `services` ou
+* `modules` n'acceptent aucun filtre, si bien que « affine la demande » nommait
+* un geste qui n'existe pas. Elle désigne ce qui EST utilisable — `count`, exact
+* et portant sur la liste entière.
+*/
+function summarize(value, size) {
+	if (Array.isArray(value)) {
+		const items = value.map(surfaceOf);
+		let rendered = JSON.stringify({
+			count: value.length,
+			note: `count = ${value.length} : c'est le nombre EXACT, il porte sur la liste entière. Les entrées ci-dessous sont ramenées à leur surface (${size} caractères au complet) — demande le détail d'une entrée précise plutôt que la liste entière`,
+			items
+		}, null, 2);
+		if (rendered.length <= 32e3) return rendered;
+		let keptCount = items.length;
+		while (keptCount > 1 && rendered.length > 32e3) {
+			keptCount = Math.floor(keptCount / 2);
+			rendered = JSON.stringify({
+				count: value.length,
+				note: `count = ${value.length} : c'est le nombre EXACT, il porte sur la liste entière. Seules ${keptCount} entrées sont montrées (la liste pèse ${size} caractères) — toute affirmation sur le NOMBRE se fonde sur count, jamais sur les entrées visibles.`,
+				items: items.slice(0, keptCount)
+			}, null, 2);
+		}
+		return rendered;
+	}
+	const keys = value && typeof value === "object" ? Object.keys(value) : void 0;
+	return JSON.stringify({
+		keys,
+		note: `réponse de ${size} caractères, trop volumineuse pour être rendue entière — demande une branche précise (par exemple le module qui t'intéresse)`
+	}, null, 2);
+}
+/**
+* Rend un résultat d'outil — les données partent en JSON COMPACT.
+*
+* Le lecteur est un agent : il relit le JSON compact sans peine, et chaque
+* caractère rendu se repaie à chaque tour suivant de sa conversation.
+* L'indentation représentait ~25 % d'un rapport `nodefony_check`.
+*
+* Exporté parce qu'une application qui déclare un outil en a besoin : sans lui,
+* chacune réinventerait l'enveloppe `content[]`, et une enveloppe mal formée
+* n'échoue pas — elle rend un résultat vide que l'agent prend pour une réponse.
+*
+* **Un résultat est BORNÉ** ({@link MCP_TEXT_MAX_CHARS}) : au-delà, il rend un
+* résumé plutôt qu'un déversement (voir {@link summarize}). La garde vit ICI, et
+* non dans chaque outil, pour qu'un outil déclaré par une
+* application en hérite sans le savoir — c'est le genre de règle qu'on
+* n'applique jamais deux fois de la même façon si on la laisse à l'appelant.
+* En deçà de la borne — le cas courant — la donnée part TELLE QUELLE : un
+* consommateur qui la parse n'a rien à changer, et on ne paie pas la garde sur
+* 100 % des appels pour 1 % de gros sujets.
+*
+* @param value - donnée à rendre (sérialisée si ce n'est pas déjà du texte)
+* @param isError - marque un échec MÉTIER (pas une faute de protocole)
+*/
+function mcpText(value, isError = false) {
+	const rendered = typeof value === "string" ? value : JSON.stringify(value);
+	const text = isError || rendered.length <= 32e3 ? rendered : summarize(value, rendered.length);
+	return isError ? {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError: true
+	} : { content: [{
+		type: "text",
+		text
+	}] };
+}
+/**
+* Forme admise pour un nom d'outil.
+*
+* Ce nom ne reste pas dans le serveur : il voyage jusque dans le contexte du
+* modèle, et sert d'identifiant d'appel. Un nom porteur d'espace, de guillemet
+* ou de saut de ligne ne provoque pas d'erreur — il produit des appels que rien
+* ne résout, ce qui est bien pire à diagnostiquer. La borne haute est du même
+* ordre : un nom de 4 000 caractères passerait, et mangerait le contexte.
+*/
+const NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Appelant anonyme — le défaut, et le seul défaut sûr. */
+const ANONYMOUS = {
+	authenticated: false,
+	scopes: [],
+	roles: []
+};
+/**
+* Préfixe RÉSERVÉ aux modules du framework (`@nodefony/*`) — un agent qui lit
+* `nodefony_inspect` doit pouvoir croire que c'est le framework qui répond.
+*
+* Sans la réserve, un module d'application pourrait déclarer `nodefony_doc` et
+* répondre à la place de l'outil que l'agent a lu dans la documentation du
+* framework : l'ordre de chargement des modules ne protège rien, il change
+* avec le manifeste.
+*/
+const MCP_RESERVED_PREFIX = "nodefony_";
+/** Portée npm des modules du framework, seuls détenteurs du préfixe réservé. */
+const FRAMEWORK_SCOPE = "@nodefony/";
+/**
+* Le module a-t-il droit au préfixe {@link MCP_RESERVED_PREFIX} ?
+*
+* Lit `getModuleName()` (le nom npm du paquet), défensivement : un module écrit
+* en JavaScript peut ne pas l'avoir, et une absence vaut refus.
+*
+* @param module - module chargé, de forme non garantie
+* @returns `true` si le module appartient à la portée `@nodefony/`
+*/
+function ownsReservedPrefix(module) {
+	if (typeof module !== "object" || module === null) return false;
+	if (!("getModuleName" in module)) return false;
+	const getName = module.getModuleName;
+	if (typeof getName !== "function") return false;
+	const name = getName.call(module);
+	return typeof name === "string" && name.startsWith(FRAMEWORK_SCOPE);
+}
+/**
+* L'appelant satisfait-il ce que l'outil exige ?
+*
+* @returns `null` s'il passe, sinon le motif de la rétention
+*/
+function withholdReason(tool, caller) {
+	const needsScopes = tool.scopes !== void 0 && tool.scopes.length > 0;
+	if (!needsScopes && tool.requiresAuth !== true) return null;
+	if (!caller.authenticated) {
+		if (tool.actsForUser === true) return "agit au nom d'un compte, l'appelant est anonyme";
+		const opened = needsScopes ? rolesFromScopes(tool.scopes) : [];
+		if (opened.length > 0 && opened.every((role) => caller.roles.includes(role))) return null;
+		return "exige une identité prouvée, l'appelant est anonyme";
+	}
+	if (!needsScopes) return null;
+	const missing = tool.scopes.filter((scope) => !caller.scopes.includes(scope));
+	return missing.length === 0 ? null : `scopes manquants : ${missing.join(", ")}`;
+}
+/**
+* Motif pour lequel une valeur rendue par `getMcpTools()` n'est pas un outil
+* servable, ou `null` si elle en est un.
+*
+* Un module peut être écrit en JavaScript : le contrat `IMcpTool` n'y est
+* vérifié par personne. `scopes` et `requiresAuth` portent l'autorisation —
+* `requiresAuth: "oui"` ne vaut pas `true` et servirait l'outil à un anonyme.
+* Une forme fausse se REFUSE à la déclaration, elle ne s'interprète jamais.
+*
+* @param tool - valeur déclarée par un module
+* @returns le motif du refus, ou `null`
+*/
+function mcpToolFault(tool) {
+	if (typeof tool !== "object" || tool === null) return "pas un objet";
+	if (!("name" in tool) || typeof tool.name !== "string" || !NAME_PATTERN.test(tool.name)) return `nom absent ou hors forme — attendu ${NAME_PATTERN.source}`;
+	if (!("handler" in tool) || typeof tool.handler !== "function") return "sans handler";
+	if (!("description" in tool) || typeof tool.description !== "string") return "`description` n'est pas une chaîne";
+	if (!("inputSchema" in tool) || typeof tool.inputSchema !== "object" || tool.inputSchema === null || Array.isArray(tool.inputSchema)) return "`inputSchema` n'est pas un objet";
+	if ("annotations" in tool && tool.annotations !== void 0 && (typeof tool.annotations !== "object" || tool.annotations === null)) return "`annotations` n'est pas un objet";
+	if ("scopes" in tool && tool.scopes !== void 0 && !(Array.isArray(tool.scopes) && tool.scopes.every((scope) => typeof scope === "string"))) return "`scopes` n'est pas un tableau de chaînes";
+	if ("scopesFor" in tool && tool.scopesFor !== void 0 && typeof tool.scopesFor !== "function") return "`scopesFor` n'est pas une fonction";
+	if ("requiresAuth" in tool && tool.requiresAuth !== void 0 && typeof tool.requiresAuth !== "boolean") return "`requiresAuth` n'est pas un booléen";
+	if ("actsForUser" in tool && tool.actsForUser !== void 0) {
+		if (typeof tool.actsForUser !== "boolean") return "`actsForUser` n'est pas un booléen";
+		if (tool.actsForUser && !("scopes" in tool && Array.isArray(tool.scopes) && tool.scopes.length > 0)) return "`actsForUser` exige des `scopes` : les rôles du compte ne sont pas bornés par le jeton";
+	}
+	return null;
+}
+/** La valeur déclarée a la forme d'un outil servable (cf {@link mcpToolFault}). */
+function isMcpTool(tool) {
+	return mcpToolFault(tool) === null;
+}
+/**
+* Énumère ce que cette application DÉCLARE — les outils de ses modules, lus
+* par `getMcpTools()` — sans rien retenir sur l'identité de qui que ce soit.
+*
+* Cinq refus, tous énoncés par `onSkip` plutôt que silencieux :
+*  - **nom hors forme** ({@link NAME_PATTERN}) — il ne serait pas appelable ;
+*  - **forme fausse** ({@link mcpToolFault}) — handler, description, schéma ou
+*    autorisation qui ne respectent pas `IMcpTool` ;
+*  - **préfixe réservé** ({@link MCP_RESERVED_PREFIX}) pris par un module hors de
+*    `@nodefony/` — un module d'application ne peut donc pas se substituer à
+*    `nodefony_inspect` et répondre à sa place ;
+*  - **collision** — le premier inscrit garde le nom ;
+*  - **déclaration en échec** — un `getMcpTools()` qui lève ne doit pas priver
+*    l'agent des outils de tous les autres modules.
+*
+* 🔴 **Ce que rend cette fonction n'est PAS servable tel quel** : elle contient
+* les outils réservés. Toute porte passe par {@link collectMcpTools}, qui filtre
+* sur l'appelant. Le seul usage légitime de la liste brute est de raisonner sur
+* le CODE — ce que la porte EXIGE ({@link mcpDeclaredScopes}) — jamais de
+* répondre à une requête.
+*
+* @param options - modules et journal des écarts
+* @returns les outils déclarés, dans l'ordre où ils seraient publiés
+*/
+function declareMcpTools(options) {
+	const declared = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (tool, origin, ownsPrefix) => {
+		const name = typeof tool === "object" && tool !== null && "name" in tool ? tool.name : void 0;
+		if (typeof name !== "string" || !NAME_PATTERN.test(name)) {
+			options.onSkip?.(`outil écarté (${origin}) : nom absent ou hors forme — attendu ${NAME_PATTERN.source}`);
+			return;
+		}
+		if (!ownsPrefix && name.startsWith("nodefony_")) {
+			options.onSkip?.(`outil « ${name} » écarté (${origin}) : le préfixe « ${MCP_RESERVED_PREFIX} » est réservé aux modules ${FRAMEWORK_SCOPE}*`);
+			return;
+		}
+		if (!isMcpTool(tool)) {
+			options.onSkip?.(`outil « ${name} » écarté (${origin}) : ${mcpToolFault(tool)}`);
+			return;
+		}
+		if (seen.has(tool.name)) {
+			options.onSkip?.(`outil « ${tool.name} » écarté (${origin}) : ce nom est déjà pris`);
+			return;
+		}
+		seen.add(tool.name);
+		declared.push(tool);
+	};
+	for (const [name, module] of Object.entries(options.modules ?? {})) {
+		if (typeof module !== "object" || module === null || !("getMcpTools" in module)) continue;
+		const declare = module.getMcpTools;
+		if (typeof declare !== "function") continue;
+		let tools;
+		try {
+			tools = declare.call(module);
+		} catch (error) {
+			options.onSkip?.(`module « ${name} » : getMcpTools() a échoué — ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		if (!Array.isArray(tools)) {
+			options.onSkip?.(`module « ${name} » : getMcpTools() doit rendre un tableau`);
+			continue;
+		}
+		const ownsPrefix = ownsReservedPrefix(module);
+		for (const tool of tools) add(tool, `module ${name}`, ownsPrefix);
+	}
+	return declared;
+}
+/**
+* Ramasse les outils SERVIS à cet appelant.
+*
+* Aux trois refus de {@link declareMcpTools} s'ajoute une RÉTENTION, qui n'est
+* pas une faute : un outil dont l'appelant ne satisfait pas les exigences
+* ({@link IMcpTool.scopes}, {@link IMcpTool.requiresAuth}) ne sort pas d'ici.
+* ⭐ **Filtrer À LA COLLECTE protège `tools/list` ET `tools/call` d'un seul
+* geste** : le protocole ne reçoit que les outils servis, donc un outil retenu
+* est « inconnu » pour lui — indistinguable d'un outil inexistant, ce qui ne
+* révèle même pas son existence. Filtrer la liste sans filtrer l'appel n'aurait
+* été qu'un rideau, et c'est l'erreur classique : deux points de décision, dont
+* un qu'on oublie.
+*
+* @param options - modules, appelant et journaux
+* @returns les outils exécutables, dans l'ordre où ils seront publiés
+*/
+function collectMcpTools(options) {
+	const caller = options.caller ?? ANONYMOUS;
+	const served = [];
+	for (const tool of declareMcpTools(options)) {
+		const withheld = withholdReason(tool, caller);
+		if (withheld !== null) {
+			options.onWithheld?.(tool.name, withheld);
+			continue;
+		}
+		served.push(tool);
+	}
+	return served;
+}
+/**
+* Le vocabulaire de scopes que cette porte EXIGE — l'union de ce que ses outils
+* déclarent, jamais une liste écrite à côté.
+*
+* 🔴 **C'est ce qu'un client doit demander**, et c'est à ce titre qu'il est
+* publié (RFC 9728 `scopes_supported`) et nommé dans le défi (RFC 6750
+* `scope`). Une liste de configuration disait autre chose que le code par
+* simple oubli, dans les deux sens et sans qu'aucun contrôle ne l'aperçoive :
+* un scope publié que rien n'exige envoie demander un droit qui n'ouvre rien ;
+* un scope exigé que rien ne publie laisse le client deviner ce qu'on attend de
+* lui — et un outil de module en était systématiquement là.
+*
+* L'énumération est délibérément celle des outils DÉCLARÉS, pas de ceux servis
+* à un appelant : le document se lit avant d'avoir un jeton, et un catalogue
+* filtré n'annoncerait à l'anonyme que ce dont il n'a pas besoin.
+*
+* @param options - modules et journal des écarts
+* @returns les scopes, dédupliqués et triés ; vide si la porte n'exige rien
+*/
+function mcpDeclaredScopes(options) {
+	const vocabulaire = /* @__PURE__ */ new Set();
+	for (const tool of declareMcpTools(options)) for (const scope of tool.scopes ?? []) vocabulaire.add(scope);
+	return [...vocabulaire].sort();
+}
+/**
+* Projette les outils pour `tools/list` — sans leur implémentation.
+*
+* Le `handler` est une fermeture sur l'état du serveur ; `JSON.stringify` le
+* laisserait tomber en silence, mais compter là-dessus reviendrait à publier
+* par accident ce qu'on ne publie pas exprès.
+*/
+function publishMcpTools(tools) {
+	return tools.map(({ name, description, inputSchema, annotations }) => annotations === void 0 ? {
+		name,
+		description,
+		inputSchema
+	} : {
+		name,
+		description,
+		inputSchema,
+		annotations
+	});
+}
+/**
+* Exécute un outil par son nom public.
+*
+* Un échec métier (sujet inconnu, module absent) rend un résultat `isError`,
+* **pas** une erreur JSON-RPC : le protocole réserve celle-ci aux fautes de
+* protocole. La distinction compte pour l'agent — une erreur de protocole
+* signifie « tu t'y prends mal », un `isError` signifie « ta demande est
+* recevable, voici pourquoi elle n'aboutit pas » ; c'est la seconde qu'il peut
+* corriger seul.
+*
+* ⭐ **Aucun contrôle d'autorisation ici, et c'est voulu** : `tools` ne contient
+* que ce que {@link collectMcpTools} a servi à CET appelant. Refaire la
+* vérification à ce niveau créerait un second point de décision — deux copies
+* d'une même règle, qui divergent en silence. Le corollaire tient en une
+* phrase : **ne jamais passer ici une liste non filtrée.**
+*
+* @param name - nom public de l'outil (`nodefony_inspect`…)
+* @param args - arguments fournis par l'agent
+* @param tools - outils servis, tels que {@link collectMcpTools} les a ramassés
+* @param caller - appelant établi, transmis au handler (anonyme par défaut)
+* @param run - annulation et progression de CET appel (détaché par défaut)
+* @returns le résultat de l'outil, ou `null` si le nom n'est pas exposé
+*/
+async function callMcpTool(name, args, tools, caller = ANONYMOUS, run = DETACHED_RUN) {
+	const tool = tools.find((candidate) => candidate.name === name);
+	if (!tool) return null;
+	const refusal = unknownArguments(tool, args);
+	if (refusal !== null) return mcpText(refusal, true);
+	const scopes = mcpCallScopes(tool, args);
+	if (scopes === null) return mcpText(`« ${tool.name} » : les scopes de cet appel sont indéterminables (\`scopesFor\` a levé ou rendu une forme fausse) — appel refusé`, true);
+	const missing = missingScopes(caller.scopes, scopes);
+	if (missing.length > 0) return mcpText(insufficientScopeMessage(tool.name, missing), true);
+	return tool.handler(args, caller, run);
+}
+/**
+* Tous les scopes qu'exige UN appel : ceux de l'outil, puis ceux que ses
+* arguments ajoutent ({@link IMcpTool.scopesFor}). Seule source de la règle,
+* lue par l'appel en process ET par le défi `insufficient_scope` d'une porte.
+*
+* @param tool - outil servi
+* @param args - arguments de l'appel
+* @returns les scopes exigés, sans doublon ; `null` si `scopesFor` lève ou rend
+*   une forme fausse (l'appel est alors refusé, jamais servi sans borne)
+*/
+function mcpCallScopes(tool, args) {
+	const base = tool.scopes ?? [];
+	if (tool.scopesFor === void 0) return base;
+	let extra;
+	try {
+		extra = tool.scopesFor(args);
+	} catch {
+		return null;
+	}
+	if (!Array.isArray(extra) || !extra.every((scope) => typeof scope === "string")) return null;
+	return extra.length === 0 ? base : [.../* @__PURE__ */ new Set([...base, ...extra])];
+}
+/**
+* Le message d'un appel refusé faute de scope — le même pour le résultat
+* `isError` et la description du défi `403`.
+*
+* @param name - nom de l'outil
+* @param missing - scopes absents du jeton
+* @returns l'explication, qui nomme les scopes à demander
+*/
+function insufficientScopeMessage(name, missing) {
+	return `« ${name} » avec ces arguments exige le(s) scope(s) ${missing.join(" ")}, absent(s) du jeton présenté — redemander un jeton qui les porte`;
+}
+/**
+* L'exécution d'un appel SANS porte qui l'observe (appel direct, test) : jamais
+* annulé, progression muette. Partagé — un signal jamais abattu ne retient rien.
+*/
+const DETACHED_RUN = {
+	signal: new AbortController().signal,
+	progress: () => {}
+};
+/**
+* Arguments que l'outil ne déclare pas — refusés, jamais ignorés.
+*
+* ⚠️ Un paramètre accepté puis jeté est pire qu'un refus : la réponse a l'air
+* d'avoir honoré la demande. Vécu sur cette porte — un `limit` passé à la
+* recherche documentaire revenait avec vingt résultats, sans un mot, et
+* l'appelant en concluait que la borne ne marchait pas plutôt que de voir
+* qu'elle n'avait jamais été transmise. Le même silence accueillait une clé
+* mal orthographiée : l'outil répondait comme si de rien n'était.
+*
+* La garde vit ICI, une fois, plutôt que dans chaque handler — et elle
+* s'applique donc aussi aux outils qu'une application déclare. Un outil qui
+* veut réellement des arguments libres l'écrit dans son schéma
+* (`additionalProperties: true`), ce qui en fait un choix relu, pas un défaut.
+*
+* @param tool - l'outil visé, avec son schéma d'entrée.
+* @param args - ce que l'agent a passé.
+* @returns le message de refus, ou `null` si tout est déclaré.
+*/
+function unknownArguments(tool, args) {
+	const schema = tool.inputSchema;
+	if (schema?.additionalProperties === true) return null;
+	const declared = schema?.properties;
+	if (!declared || typeof declared !== "object") return null;
+	const intruders = Object.keys(args).filter((key) => !Object.hasOwn(declared, key));
+	if (intruders.length === 0) return null;
+	const known = Object.keys(declared);
+	return `« ${tool.name} » ne connaît pas ${intruders.map((c) => `« ${c} »`).join(", ")}. ` + (known.length > 0 ? `Arguments acceptés : ${known.join(", ")}.` : "Cet outil ne prend aucun argument.");
+}
+export { MCP_RESERVED_PREFIX, MCP_TEXT_MAX_CHARS, callMcpTool, collectMcpTools, declareMcpTools, insufficientScopeMessage, mcpCallScopes, mcpDeclaredScopes, mcpText, publishMcpTools };

package/dist/nodefony/src/errors/AiError.js

@@ -0,0 +1,20 @@
+// nodefony/src/errors/AiError.ts
+/**
+* Erreur du module ai.
+*
+* Deux champs qui font la différence en production :
+*  - `code` : identifiant MACHINE (stable, grep-able, consommé par Studio et
+*    l'audit) — le message, lui, peut changer sans rien casser ;
+*  - `context` : payload structuré joint au log (jamais de secret ici).
+*/
+var AiError = class extends Error {
+	code;
+	context;
+	constructor(message, code = "AI_ERROR", context) {
+		super(message);
+		this.code = code;
+		this.context = context;
+		this.name = "AiError";
+	}
+};
+export { AiError, AiError as default };

package/dist/types/index.d.ts

@@ -0,0 +1,56 @@
+import { Kernel, Module } from "nodefony";
+import { type IAiConfigInput } from "./nodefony/config/config.js";
+/**
+ * @nodefony/ai — La boîte à outils IA de Nodefony : serveur MCP, puis les services de la couche agentique.
+ *
+ * Module applicatif : un workspace npm à part entière
+ * (`src/packages/@nodefony/ai/`), chargé par le manifeste `modules` de
+ * `nodefony.config.ts`. Le Kernel l'importe PAR SON NOM (`@nodefony/ai`) —
+ * d'où le workspace, qui le rend résolvable.
+ */
+/**
+ * Rend la config du module typée à l'appel : `use("@nodefony/ai", { … })`
+ * dans `nodefony.config.ts` propose les clés du schéma et refuse les fautes de
+ * frappe, au lieu d'avaler un `Record<string, unknown>`.
+ */
+declare module "nodefony" {
+    interface NodefonyModuleConfig {
+        "@nodefony/ai": IAiConfigInput;
+    }
+}
+declare class AiModule extends Module {
+    constructor(kernel: Kernel);
+    /**
+     * Valide la config au boot — défauts du schéma fusionnés avec ce que l'app
+     * passe dans `use()`. Une clé inconnue ou mal typée plante ICI, avec le champ
+     * fautif nommé, plutôt qu'en `undefined.x` au premier appel en production.
+     */
+    onKernelRegister(): Promise<this>;
+}
+export default AiModule;
+export type { IAiConfigInput } from "./nodefony/config/config.js";
+export { aiConfigSchema, mcpConfigSchema, type IAiConfig, type IMcpConfig, } from "./nodefony/config/config.js";
+export { defineAiConfig, aiConfigJsonSchema, } from "./nodefony/config/defineModuleConfig.js";
+export { MCP_PROTOCOL_VERSION, MCP_SUPPORTED_VERSIONS, MCP_DEFAULT_NEGOTIATED_VERSION, META_PROTOCOL_VERSION, META_SERVER_INFO, McpProtocolError, JsonRpcError, jsonRpcSuccess, jsonRpcFailure, isNotification, } from "./nodefony/mcp/protocol.js";
+export type { IMcpHttpReply, JsonRpcId, IJsonRpcMessage, IJsonRpcSuccess, IJsonRpcFailure, McpProtocolVersion, } from "./nodefony/mcp/protocol.js";
+export { handleMcpMessage } from "./nodefony/mcp/server.js";
+export type { IMcpServerContext, IMcpHeaders, IMcpTransport, IServerInfo, IMcpCacheHints, } from "./nodefony/mcp/server.js";
+export { defineMcpGate, mcpGateSchema, MCP_STREAM_MAX_EVENT_BYTES, } from "./nodefony/mcp/gate.js";
+export type { IMcpGate, IMcpGateDefinition, IMcpGateSettings, IMcpGateRequest, IMcpGateRuntime, IMcpGateResponse, IMcpStdioRequest, McpGateSeverity, } from "./nodefony/mcp/gate.js";
+export { serveMcpStdio } from "./nodefony/mcp/stdio.js";
+export type { IMcpStdioOptions } from "./nodefony/mcp/stdio.js";
+export { createProgressReporter, readProgressToken, MCP_PROGRESS_MIN_INTERVAL_MS, MCP_PROGRESS_MESSAGE_MAX, } from "./nodefony/mcp/progress.js";
+export type { IMcpProgressReporter, McpProgressToken, } from "./nodefony/mcp/progress.js";
+export { createMcpResponseStream, MCP_STREAM_GRACE_MS, } from "./nodefony/mcp/stream.js";
+export type { IMcpEventSink, IMcpResponseStream, IMcpResponseStreamOptions, } from "./nodefony/mcp/stream.js";
+export { checkMcpAccess, isLocalAddress, isRelayedRequest, RELAY_HEADERS, } from "./nodefony/mcp/guard.js";
+export type { GuardVerdict, IGuardInput, IGuardPolicy, } from "./nodefony/mcp/guard.js";
+export { SESSION_TICKET_HEADER, SESSION_TICKET_LENGTH, SESSION_TICKET_MAX_PENDING, SESSION_TICKET_TTL_MS, SessionTicketStore, fingerprintSessionTicket, } from "./nodefony/mcp/sessionTicket.js";
+export type { ISessionTicketStoreOptions } from "./nodefony/mcp/sessionTicket.js";
+export { TICKET_SESSION_REFUSED, defineTicketSessionGate, isSessionFlowView, isSessionServiceView, openTicketSession, readTicketSessionVerdict, ticketSessionGateSchema, toTicketSessionUser, } from "./nodefony/mcp/ticketSession.js";
+export type { ISessionFlowView, ISessionServiceView, ITicketSessionDeps, ITicketSessionGate, ITicketSessionGateDefinition, ITicketSessionGateSettings, ITicketSessionRequest, ITicketSessionUser, TicketSessionVerdict, } from "./nodefony/mcp/ticketSession.js";
+export { mcpCallerRoles } from "./nodefony/mcp/caller.js";
+export type { IMcpGatePosture } from "./nodefony/mcp/caller.js";
+export { mcpText, declareMcpTools, collectMcpTools, mcpDeclaredScopes, mcpCallScopes, insufficientScopeMessage, publishMcpTools, callMcpTool, MCP_TEXT_MAX_CHARS, MCP_RESERVED_PREFIX, } from "./nodefony/mcp/tools.js";
+export type { IMcpTool, IMcpToolAnnotations, IMcpToolDefinition, IMcpToolResult, IMcpCaller, IMcpToolRun, IMcpDeclareOptions, IMcpCollectOptions, } from "./nodefony/mcp/tools.js";
+export { AiError } from "./nodefony/src/errors/AiError.js";

package/dist/types/nodefony/command/StdioCommand.d.ts

@@ -0,0 +1,28 @@
+import { Command, CliKernel } from "nodefony";
+/**
+ * Sert le MCP de l'application sur l'entrée et la sortie standard —
+ * `nodefony ai:stdio`.
+ *
+ * Pour le client qui lance lui-même son serveur MCP et lui parle par stdio
+ * (agent de CI, interface en ligne de commande, agent cloud `"type": "local"`) :
+ * rien n'y écoute sur `localhost`, la route `/nodefony/mcp` lui est hors
+ * d'atteinte.
+ *
+ * Servi dans TOUS les environnements : les outils des modules chargés, avec la
+ * posture de l'OPÉRATEUR LOCAL — celle de toute commande du CLI
+ * (`localOperatorCaller`, qui dit pourquoi). Qui lance la commande a déjà un
+ * terminal dans l'application : `nodefony inspect` lui rend les mêmes données.
+ * Ce rôle n'ouvre que l'administration du framework (`admin:read`/`admin:write`
+ * se traduisent en lui, `rolesFromScopes`) ; un outil à scope APPLICATIF, un
+ * outil `requiresAuth` ou `actsForUser` reste retenu — il exige un jeton, donc
+ * une porte HTTP protégée. Les outils `nodefony_*` n'y paraissent que lorsque
+ * `@nodefony/devkit` est chargé (développement).
+ *
+ * Limite : le code servi est celui du boot, sans rechargement à chaud — la
+ * porte HTTP de développement reste celle qui suit les sources.
+ */
+declare class StdioCommand extends Command {
+    constructor(cli: CliKernel);
+    generate(): Promise<this>;
+}
+export default StdioCommand;

package/dist/types/nodefony/config/config.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+/**
+ * Réglages de la porte MCP (`POST /nodefony/mcp`) — la SOURCE UNIQUE du schéma
+ * `mcp.*`, que tout module qui sert ou configure la porte importe d'ici.
+ *
+ * Les outils exposés ne se règlent PAS ici : chaque module déclare les siens
+ * (`getMcpTools()`), et un module qui veut filtrer son propre catalogue porte ce
+ * réglage dans SA config.
+ *
+ * Tant qu'aucun serveur d'autorisation n'est déclaré, la porte n'est protégée
+ * que par les deux gardes que la spec impose au transport ({@link allowedOrigins},
+ * {@link allowRemote}) — qui visent le risque réel d'une porte locale : une page
+ * web ouverte dans le navigateur du développeur.
+ *
+ * ⚠️ **Piège Zod 4** : un `.default({})` posé à plat sur un sous-objet NE
+ * ré-applique PAS les défauts de ses champs. Le pattern du dépôt est donc
+ * `sous.default(() => sous.parse({}))` — le callback force la ré-évaluation, et
+ * une application qui n'écrit rien obtient bien les valeurs d'usine.
+ */
+export declare const mcpConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    allowRemote: z.ZodDefault<z.ZodBoolean>;
+    authorization: z.ZodDefault<z.ZodObject<{
+        authorizationServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        resource: z.ZodDefault<z.ZodString>;
+        additionalResources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        resourceName: z.ZodOptional<z.ZodString>;
+        resourceDocumentation: z.ZodOptional<z.ZodString>;
+        anonymous: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const aiConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Réglages `mcp.*` tels que le CODE les lit — défauts appliqués. */
+export type IMcpConfig = z.output<typeof mcpConfigSchema>;
+/** Config telle que l'APP l'écrit dans `use()` — tous les champs optionnels. */
+export type IAiConfigInput = z.input<typeof aiConfigSchema>;
+/** Config telle que le CODE la lit — défauts appliqués, rien d'optionnel. */
+export type IAiConfig = z.output<typeof aiConfigSchema>;
+/** Défauts matérialisés (passés au `super()` du Module). */
+declare const defaults: IAiConfig;
+export default defaults;

package/dist/types/nodefony/config/configSchema.d.ts

@@ -0,0 +1,12 @@
+/**
+ * JSON Schema de la configuration de @nodefony/ai — lu SANS démarrer
+ * l'application, par `nodefony env` et la notice `.env.example`, qui y
+ * trouvent les noms courts (`.meta({ env })`).
+ *
+ * Déclaré dans `package.json` → `nodefony.configSchema` ; le nom de l'export
+ * est FIXE. Fichier FEUILLE : il n'importe que zod et le schéma, et n'ouvre
+ * rien à l'import — une commande qui ne démarre pas l'application l'exécute.
+ *
+ * @returns le JSON Schema, métadonnées Nodefony comprises.
+ */
+export declare function configJsonSchema(): unknown;