@nodefony/devkit 10.0.0-beta.3 → 10.0.0-beta.4

package/dist/types/nodefony/mcp/profileRoute.d.ts

@@ -0,0 +1,87 @@
+import { type IMcpCaller, type IMcpTool, type IRolesWithin } from "nodefony";
+import { type IProfilerReader } from "@nodefony/http";
+import { type IObserveProbe } from "./observe.js";
+import { type RequestLogs } from "./profileReport.js";
+import { type IShotClient, type IShotTarget } from "./shotClient.js";
+import { type OnShutdown } from "./shutdown.js";
+/** Requêtes mesurées par défaut. */
+export declare const PROFILE_ROUTE_DEFAULT_COUNT = 50;
+/**
+ * Requêtes mesurées au plus. Avec la chauffe, sous les 500 profils que garde le
+ * profileur : au-delà, les premiers seraient évincés avant d'être lus.
+ */
+export declare const PROFILE_ROUTE_MAX_COUNT = 200;
+/** Requêtes simultanées par défaut. */
+export declare const PROFILE_ROUTE_DEFAULT_CONCURRENCY = 4;
+/** Requêtes simultanées au plus : mesurer une route, pas saturer le process. */
+export declare const PROFILE_ROUTE_MAX_CONCURRENCY = 8;
+/** Requêtes de chauffe par défaut, tirées AVANT et hors des mesures. */
+export declare const PROFILE_ROUTE_DEFAULT_WARMUP = 3;
+/** Requêtes de chauffe au plus. */
+export declare const PROFILE_ROUTE_MAX_WARMUP = 20;
+/**
+ * Budget de temps d'un tir, en ms. Sous les 60 s qu'un client MCP attend par
+ * défaut : au-delà, l'agent couperait l'appel juste avant le rapport.
+ */
+export declare const PROFILE_ROUTE_BUDGET_MS = 45000;
+/**
+ * Attente maximale, en ms, d'un profil après la réponse : le profileur le
+ * collecte au `close` de la réponse, émis en différé — rien ne garantit qu'il
+ * précède la fin de lecture côté client, dans le même process.
+ */
+export declare const PROFILE_COLLECT_WAIT_MS = 500;
+/** Ce dont l'outil a besoin — injecté, pour l'éprouver sans application. */
+export interface IProfileRouteDeps {
+    /** Le profileur de l'application, ou `undefined` hors développement. */
+    getProfiler: () => IProfilerReader | undefined;
+    /**
+     * Ce process sert-il des requêtes ? Rend `false` sous la porte stdio :
+     * l'outil le dit ({@link NOT_SERVING_MESSAGE}). Absent : supposé servir.
+     */
+    servesTraffic?: (() => boolean) | undefined;
+    /** L'adresse d'écoute HTTP en clair de l'application, ou `null`. */
+    getTarget: () => IShotTarget | null;
+    /** Fabrique du client du tir (défaut : `node:http`, cf {@link createShotClient}). */
+    createClient?: ((target: IShotTarget, concurrency: number) => IShotClient) | undefined;
+    /** Fabrique de la sonde du process (défaut : `ProcessProbe` du cœur). */
+    createProbe?: (() => IObserveProbe) | undefined;
+    /** Émet le ticket à usage unique qui ouvrira la session de `identifier`. */
+    issueTicket?: ((identifier: string) => string) | undefined;
+    /** Détruit la session de profilage désignée par son pseudonyme. */
+    closeSession?: ((ref: string) => Promise<unknown>) | undefined;
+    /** Les rôles de `target` sont-ils inclus dans ceux de `owner` (hiérarchie comprise) ? */
+    rolesWithin?: IRolesWithin | undefined;
+    /** Lit les lignes de journal d'une requête en erreur. */
+    readRequestLogs?: ((requestId: string, caller: IMcpCaller) => Promise<RequestLogs>) | undefined;
+    /** S'abonne à l'arrêt du serveur pour la durée d'un appel. */
+    onShutdown?: OnShutdown | undefined;
+    /** Attente d'un profil après sa réponse (défaut {@link PROFILE_COLLECT_WAIT_MS}). */
+    collectWaitMs?: number | undefined;
+    /** Budget du tir (défaut {@link PROFILE_ROUTE_BUDGET_MS}). */
+    budgetMs?: number | undefined;
+}
+/**
+ * Contrôle le chemin à profiler : un CHEMIN de l'application, jamais une URL —
+ * l'outil ne doit pouvoir viser qu'elle.
+ *
+ * @param raw - l'argument `path`, non fiable.
+ * @returns le chemin normalisé (fragment retiré), ou la raison du refus.
+ */
+export declare function checkProfilePath(raw: unknown): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * L'outil `nodefony_profile_route` : envoie lui-même N requêtes à une route de
+ * l'application, au nom d'un compte s'il le faut, et rend leur profil agrégé.
+ *
+ * Rien n'est armé hors d'un appel : le client du tir (ses connexions), la
+ * session de profilage et l'écoute de l'arrêt du serveur naissent avec l'appel
+ * et sont libérés à sa sortie, quelle qu'elle soit.
+ *
+ * @param deps - profileur, adresse d'écoute, ouverture de session, journal.
+ */
+export declare function profileRouteTool(deps: IProfileRouteDeps): IMcpTool;

package/dist/types/nodefony/mcp/shotClient.d.ts

@@ -0,0 +1,53 @@
+/** Délai d'une requête du tir, en ms : au-delà, elle compte « sans réponse ». */
+export declare const SHOT_REQUEST_TIMEOUT_MS = 15000;
+/** Où l'application écoute, vue de son propre process. */
+export interface IShotTarget {
+    /** Adresse de connexion (boucle locale). */
+    host: string;
+    port: number;
+    /** En-tête `Host` envoyé : le domaine que l'application attend. */
+    hostHeader: string;
+}
+/** Une requête du tir. */
+export interface IShotRequest {
+    method: "GET" | "HEAD" | "POST";
+    path: string;
+    headers: Readonly<Record<string, string>>;
+    /** Lire le corps de la réponse (connexion seulement ; un tir le jette). */
+    readBody?: boolean | undefined;
+}
+/** Ce que le client retient d'une réponse. */
+export interface IShotResponse {
+    status: number;
+    location: string | null;
+    setCookie: readonly string[];
+    body: string | null;
+}
+/** Le client d'UN tir : ses connexions vivent le temps de l'appel. */
+export interface IShotClient {
+    send(request: IShotRequest, signal: AbortSignal): Promise<IShotResponse>;
+    /** Ferme les connexions gardées ouvertes ; les requêtes en vol échouent. */
+    close(): void;
+}
+/**
+ * Client `node:http` d'un tir : connexions gardées ouvertes entre deux requêtes,
+ * comme un navigateur, au plus `concurrency` à la fois, toutes fermées par
+ * `close()`. Un `fetch` passerait par un pool global, qui survivrait à l'appel.
+ *
+ * @param target - l'adresse d'écoute de l'application.
+ * @param concurrency - connexions simultanées au plus.
+ * @returns le client, à fermer en fin de tir.
+ */
+export declare function createShotClient(target: IShotTarget, concurrency: number): IShotClient;
+/**
+ * Lit l'adresse d'écoute du serveur HTTP en clair de l'application (service
+ * `server-http`), telle qu'il l'a réellement obtenue — port de repli compris.
+ *
+ * Une écoute sur toutes les interfaces (`0.0.0.0`, `::`) se joint par la boucle
+ * locale : c'est aussi ce qui rend l'appel LOCAL pour la route de connexion du
+ * profilage.
+ *
+ * @param server - ce que le conteneur rend pour `server-http`.
+ * @returns la cible, ou `null` si aucun serveur n'est prêt.
+ */
+export declare function readShotTarget(server: unknown): IShotTarget | null;

package/dist/types/nodefony/mcp/shutdown.d.ts

@@ -0,0 +1,25 @@
+import type { IMcpToolRun } from "nodefony";
+/** Abonnement à l'arrêt du serveur, pour la durée d'UN appel d'outil. */
+export type OnShutdown = (listener: () => Promise<void>) => () => void;
+/** Ce qu'un outil long lit pour savoir s'il doit s'arrêter, et pourquoi. */
+export interface IToolStop {
+    /** Avorté quand l'agent abandonne l'appel OU que le serveur s'arrête. */
+    readonly signal: AbortSignal;
+    /** `true` si c'est l'arrêt du serveur qui a clos l'appel. */
+    readonly interrupted: boolean;
+    /**
+     * Le rapport est rendu : l'arrêt du serveur, s'il attendait, reprend, et
+     * l'écouteur quitte le kernel. À appeler sur TOUS les chemins de sortie.
+     */
+    release(): void;
+}
+/**
+ * Arme l'arrêt d'un outil long : l'agent qui abandonne, ou le serveur qui
+ * s'arrête (rechargement après une modification de fichier). Dans le second
+ * cas, l'arrêt attend — borné — que le rapport partiel soit parti.
+ *
+ * @param run - l'appel en cours, porteur du signal d'abandon de l'agent.
+ * @param onShutdown - abonnement à l'arrêt du serveur ; absent hors application.
+ * @returns le signal combiné, la cause, et la libération.
+ */
+export declare function watchToolStop(run: IMcpToolRun | undefined, onShutdown: OnShutdown | undefined): IToolStop;

package/dist/types/nodefony/mcp/tools.d.ts

@@ -0,0 +1,109 @@
+import { skippedChecks } from "nodefony";
+import type { IDoctorReport, IAdminBrokerLike, IMcpTool } from "nodefony";
+import type { IProfilerReader } from "@nodefony/http";
+import { type IProfileRouteDeps } from "./profileRoute.js";
+/** Ce dont les outils INTÉGRÉS ont besoin — injecté, jamais lu ici. */
+export interface IMcpToolDeps {
+    /** Le service `adminBroker` du conteneur, ou `undefined` s'il manque. */
+    broker: IAdminBrokerLike | undefined;
+    /** Compose la carte de visite de l'application. */
+    getCard: () => unknown;
+    /**
+     * Racine depuis laquelle lire le disque (graphe symbolique, diagnostic).
+     *
+     * Injectée plutôt que lue par `process.cwd()` : le serveur répond dans le
+     * process de l'application, dont le dossier courant n'est pas garanti être
+     * celui du projet — et un outil qui diagnostiquerait le mauvais dossier
+     * conclurait « rien à signaler » avec aplomb.
+     */
+    projectRoot: string;
+    /**
+     * Le profileur de développement (`"profiler"` du conteneur), ou `undefined`
+     * hors développement : `nodefony_observe` le dit au lieu de planter.
+     */
+    getProfiler: () => IProfilerReader | undefined;
+    /**
+     * Ce process sert-il des requêtes ? `false` sous la porte stdio, où les
+     * outils de MESURE refusent en le disant ; absent : supposé servir.
+     */
+    servesTraffic?: (() => boolean) | undefined;
+    /**
+     * S'abonne à l'arrêt du serveur pour la durée d'un appel (rapport partiel de
+     * `nodefony_observe`) ; absent hors application.
+     */
+    onShutdown?: ((listener: () => Promise<void>) => () => void) | undefined;
+    /**
+     * Ce que `nodefony_profile_route` demande à l'application : son adresse
+     * d'écoute, l'ouverture et la fermeture de la session de profilage, la
+     * comparaison des rôles de deux comptes. Absent hors application : l'outil
+     * dit qu'il n'a rien à viser.
+     */
+    profileRoute?: Pick<IProfileRouteDeps, "getTarget" | "issueTicket" | "closeSession" | "rolesWithin"> | undefined;
+}
+/**
+ * Clés des outils intégrés — ce que l'allowlist de configuration nomme.
+ *
+ * Publiée pour qu'un schéma de configuration puisse la valider au lieu de la
+ * retaper : une clé inconnue en config est silencieusement sans effet, et
+ * l'utilisateur croit avoir activé quelque chose.
+ */
+export declare const BUILTIN_MCP_TOOL_KEYS: readonly ["inspect", "card", "check", "symbols", "docs", "admin_list", "admin_call", "observe", "profile_route"];
+/** Clé d'un outil intégré. */
+export type BuiltinMcpToolKey = (typeof BUILTIN_MCP_TOOL_KEYS)[number];
+/** Contrôles sautés pour la MÊME raison : la raison une fois, ses familles ensuite. */
+export interface ISkippedCheckGroup {
+    /** Famille → titre, dans l'ordre de lecture du rapport. */
+    families: Record<string, string>;
+    reason: string;
+    unlock?: string | undefined;
+    onDemand?: boolean | undefined;
+    notApplicable?: boolean | undefined;
+    advisory?: boolean | undefined;
+}
+/**
+ * Regroupe les contrôles sautés qui disent exactement la même chose.
+ *
+ * Sur l'application de développement, sept familles sautées partagent trois
+ * raisons : les répéter famille par famille coûtait ~1 800 caractères à chaque
+ * appel, relus ensuite à chaque tour de l'agent.
+ *
+ * @param skipped - les contrôles sautés, dans l'ordre du rapport
+ * @returns un groupe par raison distincte, dans l'ordre de première apparition
+ */
+export declare function groupSkippedChecks(skipped: ReturnType<typeof skippedChecks>): ISkippedCheckGroup[];
+/**
+ * Taille le rapport de diagnostic pour un AGENT : les mêmes faits, sans redite.
+ *
+ * Le `--json` de `nodefony doctor` reste complet ; seule la porte MCP taille,
+ * parce que ce qu'elle rend se relit à chaque tour suivant de l'agent. Trois
+ * coupes : `execution` (que `skipped` résume déjà), les raisons de `skipped`
+ * regroupées ({@link groupSkippedChecks}), les liens `open` des derniers
+ * démarrages (faits pour un humain qui clique).
+ *
+ * @param report - le rapport de `collectDoctorReport`
+ * @returns le verdict, son compte, puis le rapport sans redite
+ */
+export declare function compactDoctorReport(report: IDoctorReport): Record<string, unknown>;
+/**
+ * Catalogue intégré du framework, indexé par clé d'allowlist.
+ *
+ * Chaque handler capture ses dépendances par fermeture : c'est ce qui permet à
+ * ces outils d'être des {@link IMcpTool} ordinaires, du même type que
+ * ceux d'une application — le serveur n'a plus aucun cas particulier à traiter.
+ *
+ * @param deps - briques qui répondent réellement
+ */
+export declare function builtinMcpTools(deps: IMcpToolDeps): Record<BuiltinMcpToolKey, IMcpTool>;
+/**
+ * Les outils du catalogue que l'allowlist de configuration retient.
+ *
+ * C'est la forme sous laquelle `@nodefony/devkit` les déclare (`getMcpTools()`) :
+ * des {@link IMcpTool} ordinaires, collectés par `@nodefony/ai` comme ceux de
+ * n'importe quel module — seul le préfixe `nodefony_`, réservé aux modules
+ * `@nodefony/*`, les distingue.
+ *
+ * @param allowlist - clés courtes retenues (cf {@link BUILTIN_MCP_TOOL_KEYS})
+ * @param deps - briques qui répondent réellement
+ * @returns les outils retenus, dans l'ordre de l'allowlist
+ */
+export declare function selectBuiltinMcpTools(allowlist: readonly string[], deps: IMcpToolDeps): IMcpTool[];

package/dist/types/nodefony/service/DevkitService.d.ts

@@ -1,5 +1,7 @@
 import { Service, Module } from "nodefony";
-import type { IMcpToolDeps, IProtectedResourceInput } from "nodefony";
+import type { IMcpTool, IProtectedResourceInput } from "nodefony";
+import { type IMcpGate, type ITicketSessionGate } from "@nodefony/ai";
+import { type IMcpToolDeps } from "../mcp/tools.js";
 import type { IDevkitCard, IDevkitService } from "../interfaces/IDevkitService.js";
 import { type IDevkitConfig } from "../config/config.js";
 /**
@@ -12,7 +14,7 @@ import { type IDevkitConfig } from "../config/config.js";
  *
  * Un service porte DEUX noms, et c'est normal :
  *   `@injectable()`             → nomme la CLASSE (`DevkitService`),
- *                                 c'est ce qu'on écrit dans `@inject("…")`
+ *                                 c'est ce qu'on écrit dans `@Inject("…")`
  *   `super("devkit", …)` → nomme l'INSTANCE, sa clé dans le conteneur,
  *                                 c'est ce qu'on écrit dans `kernel.get("…")`
  * Les deux mènent à la MÊME instance : le conteneur les réconcilie via la classe.
@@ -28,13 +30,13 @@ import { type IDevkitConfig } from "../config/config.js";
  * ```ts
  * // 1. INJECTION par le constructeur — la dépendance est DÉCLARÉE, donc le
  * //    conteneur l'ordonnance et elle se voit dans la signature (nom de CLASSE).
- * import { inject, injectable, Service, Module } from "nodefony";
+ * import { Inject, injectable, Service, Module } from "nodefony";
  *
  * @injectable()
  * class ReportService extends Service {
  *   constructor(
  *     module: Module,
- *     @inject("DevkitService") private devkit: DevkitService,
+ *     @Inject("DevkitService") private devkit: DevkitService,
  *   ) {
  *     super("report", module.container, module.notificationsCenter);
  *   }
@@ -46,6 +48,7 @@ import { type IDevkitConfig } from "../config/config.js";
  * ```
  */
 declare class DevkitService extends Service implements IDevkitService {
+    #private;
     module: Module;
     private readonly cfg;
     constructor(module: Module);
@@ -97,6 +100,16 @@ declare class DevkitService extends Service implements IDevkitService {
      *          n'est pas garanti être celui du projet).
      */
     mcpToolDeps(): IMcpToolDeps;
+    /**
+     * Les outils `nodefony_*` retenus par l'allowlist `mcp.tools`.
+     *
+     * Recomposés à chaque appel, jamais mémorisés : la collecte a lieu à la
+     * requête MCP, sur une porte qui n'existe qu'en développement — un cache
+     * serait une structure de plus à invalider pour un gain nul.
+     *
+     * @returns les outils, dans l'ordre de l'allowlist
+     */
+    mcpTools(): IMcpTool[];
     /**
      * Les scopes que la porte MCP EXIGE — dérivés des outils qu'elle déclare.
      *
@@ -136,6 +149,30 @@ declare class DevkitService extends Service implements IDevkitService {
      * @returns une entrée pour la porte MCP, ou aucune
      */
     publishedProtectedResources(): readonly IProtectedResourceInput[];
+    /**
+     * La porte MCP de développement — définie au premier usage, une fois.
+     *
+     * Bâtie sur `defineMcpGate` comme celle de n'importe quelle application : ses
+     * réglages viennent de `devkit.mcp.*`, elle sert les outils de TOUS les modules
+     * chargés (`tools: "modules"` — l'outillage éprouve aussi ceux de l'app), et
+     * accorde le rôle d'opérateur à qui l'atteint sans jeton. Ce rôle n'est sûr que
+     * parce que son PÉRIMÈTRE la protège (module `policy: "dev"`, absent en
+     * production) ; une porte protégée par un serveur d'autorisation le tire, elle,
+     * des scopes du jeton.
+     *
+     * @returns la porte, prête à servir.
+     */
+    mcpGate(): IMcpGate;
+    /**
+     * La porte de session du profilage — définie au premier usage, une fois.
+     *
+     * Bâtie sur `defineTicketSessionGate` comme le ferait une application pour
+     * ses propres outils : locale seulement (défaut de la porte), facteur d'audit
+     * {@link PROFILE_SESSION_FACTOR}.
+     *
+     * @returns la porte, prête à émettre et à servir.
+     */
+    profileSessionGate(): ITicketSessionGate;
     status(): {
         ready: boolean;
     };

package/dist/types/nodefony/src/profileSession.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Facteur d'authentification déclaré au flux de session : l'audit écrit
+ * `login.success` avec cette raison, ce qui distingue une session de profilage
+ * d'une vraie connexion.
+ */
+export declare const PROFILE_SESSION_FACTOR = "devkit";
+/**
+ * Chemin de la route de connexion du profilage, que l'outil appelle. Hors du
+ * motif de la zone d'administration (`^/nodefony/[^/]+/api`). Le contrôleur
+ * l'écrit en littéraux ; un test tient l'égalité.
+ */
+export declare const PROFILE_SESSION_PATH = "/nodefony/devkit/profile-session";

package/docs/index.md

@@ -106,13 +106,13 @@ la rend éprouvable sans serveur, et ce qui l'empêche d'inventer quoi que ce so
 npx nodefony ai:mcp        # écrit .mcp.json ; --dry-run pour voir sans écrire
 ```
 
-Sept outils. Quatre sont les commandes que vous connaissez déjà :
+Neuf outils. Quatre sont les commandes que vous connaissez déjà :
 `nodefony_inspect` (ce qui est monté), `nodefony_check` (ce qui manque),
 `nodefony_symbols` (ce qu'une API signifie), `nodefony_card` (par où commencer).
 `nodefony_docs` sert la documentation des modules. `nodefony_admin_list` et
 `nodefony_admin_call` ouvrent les lectures du data plane d'administration — le
 catalogue, puis l'appel — et exigent un jeton porteur du scope `admin:read` :
-sans lui, ils n'apparaissent pas dans la liste.
+sans lui, ils n'apparaissent pas dans la liste. `nodefony_observe` mesure ce que l'application fait réellement de ses requêtes, pendant qu'elle tourne ; `nodefony_profile_route` mesure une route en lui envoyant lui-même ses requêtes (sections suivantes).
 
 **Il n'y a pas de process à lancer.** Depuis la révision `2026-07-28` du
 transport, un serveur MCP est un endpoint `POST` sans session : c'est donc une
@@ -143,13 +143,145 @@ Trois choses à savoir avant de s'étonner d'un refus :
 
 Les outils intégrés sont en lecture seule, et `mcp.tools` est une allowlist.
 
-### Obtenir le porteur — `security:token`
+### Mesurer l'application qui tourne — `nodefony_observe`
+
+Un agent de code qui vient de modifier un contrôleur ne voit pas l'effet de son
+changement : la barre de debug et la console d'administration affichent les
+mesures du profileur, mais il ne les lit pas. `nodefony_observe` les lui rend.
+Pendant une fenêtre de 1 à 50 secondes (10 par défaut), l'outil relève le
+profileur de développement toutes les deux secondes et rend un rapport :
+
+1. un **verdict** — `ok`, `anomalies (N)`, et `INCOMPLÈTE` quand les chiffres ne
+   portent pas sur tout (profils perdus, aucun trafic, appel interrompu), avec
+   la raison ;
+2. les **anomalies**, nommées par route et par contrôleur : une requête SQL
+   répétée dans une boucle (« N+1 »), les erreurs `5xx` avec leur `requestId` et
+   leurs lignes de journal, les routes dont le p95 dépasse 500 ms avec ce qui
+   coûte par requête, un blocage de la boucle d'événements de 100 ms ou plus ;
+3. un tableau par route, les requêtes SQL les plus coûteuses, et un bloc JSON
+   pour comparer deux appels — avant et après une correction.
+
+```jsonc
+{ "name": "nodefony_observe", "arguments": { "durationSec": 10 } }
+// "route": "<nom de route>" pour n'en observer qu'une ; "includeTooling": true
+// pour compter aussi les routes /nodefony/… de l'outillage
+```
+
+**L'outil ne génère aucun trafic.** On ouvre la page, on joue les tests ou on
+envoie des requêtes pendant que la fenêtre court ; sans trafic, il n'a rien à
+juger, et il le dit.
+
+Ce que les chiffres veulent dire :
+
+- **durées et temps « par requête »** portent sur les requêtes **servies**
+  (statut inférieur à 400, sans exception). Un refus `401`/`403` rendu en
+  quelques millisecondes ne mesure pas la route : il est compté à part ;
+- **`action.self`** est le temps de l'action et des services qu'elle appelle,
+  une fois retirés les phases imbriquées (initialisation, rendu, envoi) et le
+  SQL — les intervalles sont fusionnés, une requête lancée pendant le rendu
+  n'est pas comptée deux fois. **« SQL (cumul) »** additionne les durées des
+  requêtes, même lancées en parallèle ;
+- **la boucle d'événements** est rapportée en retard moyen et en **pire
+  blocage** : un gel unique de 200 ms ne déplace la moyenne d'un intervalle de
+  deux secondes que de quelques millisecondes ;
+- **la forme d'une requête SQL** remplace chaque valeur par `?` : le rapport ne
+  contient jamais une donnée. Le journal d'une erreur n'en garde que les lignes
+  WARNING et plus graves ;
+- la **variation du tas** est mesurée sans GC forcé : elle est indicative,
+  jamais une anomalie.
+
+Ce qui encadre l'outil :
+
+- c'est un **outil long** : chaque relevé part en progression, et un client qui l'annule l'arrête au relevé suivant, qu'il ferme le flux de la réponse (révision courante de MCP) ou envoie une notification d'annulation (révision précédente, celle du SDK officiel) ;
+- un **rechargement du serveur** pendant la fenêtre (un fichier modifié) ne fait
+  pas perdre l'observation : l'outil rend un rapport partiel qui le dit, avant
+  que le serveur ne ferme ses connexions ;
+- le **journal des erreurs** est lu au relevé qui voit la requête — le syslog de
+  développement ne garde que ses dernières lignes — et seulement pour un appel
+  **authentifié** (scope `admin:read`), par la même voie que
+  `nodefony_admin_call` ;
+- le profileur garde les 500 dernières requêtes : au-delà de ce débit entre deux
+  relevés, les profils perdus sont comptés, et le verdict le dit.
+
+La lecture de chaque anomalie et le geste qui la corrige sont dans le skill
+d'agent `nodefony-troubleshoot`, section « Mesurer l'application qui tourne ».
+
+### Mesurer une route — `nodefony_profile_route`
+
+Là où `nodefony_observe` attend le trafic, `nodefony_profile_route` le **produit** :
+il envoie lui-même N requêtes `GET` (ou `HEAD`) sur un chemin de l'application,
+retrouve leurs profils par l'identifiant qu'il pose (`x-request-id`) et rend le
+même rapport. C'est la boucle « je modifie → je mesure » en un appel.
+
+```jsonc
+// tools/call
+{
+  "name": "nodefony_profile_route",
+  "arguments": { "path": "/orders?page=2", "count": 50 },
+}
+// optionnel : "concurrency" (défaut 4, max 8), "warmup" (défaut 3, hors mesures),
+//             "method": "HEAD", "as": "<identifiant>", "anonymous": true
+```
+
+`path` est un **chemin**, jamais une URL : hôte, schéma et `//` sont refusés,
+l'outil ne vise que l'application elle-même. Au plus 200 requêtes par appel —
+sous les 500 profils que garde le profileur — et 45 secondes de tir.
+
+**Au nom de qui.** Une page protégée vue sans compte ne rend que des refus.
+Quand le jeton MCP porte le scope `admin:write`, l'outil joue son
+**propriétaire** : il ouvre une vraie session à son nom par le flux de connexion
+de l'application (un ticket à usage unique, présenté en boucle locale à
+`POST /nodefony/devkit/profile-session`), tire avec, puis la détruit — l'audit
+l'écrit sous la raison `devkit`. `as` joue un autre compte, à condition que ses
+rôles soient inclus dans ceux du propriétaire, hiérarchie comprise : jouer un
+compte ne monte jamais en droits. Sans ce scope, l'outil joue l'anonyme et le
+rapport donne la commande :
+
+```bash
+npx nodefony security:mcp:token --scope "admin:read admin:write" --write
+```
+
+Extrait de deux appels réels, avant puis après la correction d'un N+1 (la même
+lecture, une requête par compte, puis une seule requête `$in`) :
+
+```text
+Verdict : anomalies (1) — observation complète
+Tir : 30/30 requête(s) GET /nodefony/test/db/n-plus-one · concurrence 4 · 106 ms · chauffe de 3 requête(s) hors mesures (p50 1.5 ms, max 2.5 ms)
+Joué en tant que : `admin` (ROLE_ADMIN, ROLE_NODEFONY_ADMIN, ROLE_DEV, ROLE_SUPERVISOR)
+Reçu par le client : 2xx 30 · 3xx 0 · 401 0 · 403 0 · autres 4xx 0 · 5xx 0 · sans réponse 0
+
+Anomalies (les plus coûteuses d'abord) :
+1. N+1 — route `DbController::nPlusOne` (DbController.nPlusOne) : `select … from "User" where "User"."id" = ? …` répétée ×16 dans une requête (30 requête(s) touchée(s), 14 ms cumulés). […] Remède habituel : charger la relation en une requête (`relations`, `$in`).
+
+route | type | n | p50 | p95 | max | 2xx/3xx/4xx/5xx | SQL par requête moy/max | temps par requête
+`DbController::nPlusOne` (DbController.nPlusOne) | http | 30 | 1.2 ms | 1.7 ms | 1.7 ms | 30/0/0/0 | 18.0/18 | SQL (cumul) 0.7 ms · action.self 0.2 ms · send 0.1 ms
+
+— après correction —
+Verdict : ok — observation complète
+`DbController::nPlusOneFixed` (DbController.nPlusOneFixed) | http | 30 | 0.7 ms | 0.9 ms | 2.1 ms | 30/0/0/0 | 3.0/3 | SQL (cumul) 0.4 ms · send 0.1 ms · action.self 0.1 ms
+```
+
+Ce que le rapport dit **en tête**, avant tout chiffre : les requêtes refusées
+(`401`/`403` — verdict « rien à juger »), redirigées (vers la page de
+connexion), restées sans réponse, et les profils non retrouvés. Une mesure qui ne
+porte pas sur ce qui était demandé le dit d'abord.
+
+À savoir :
+
+- ce sont de **vraies requêtes** : une page qui écrit en `GET` écrit N fois — un
+  compteur, ou une session créée pour chaque visiteur anonyme ;
+- les zones à jeton (`jwt`, `external-jwt`) ne sont pas jouées : leurs requêtes
+  rendent `401`, et le rapport le dit ;
+- un tir plus court que cinq périodes de la sonde laisse la boucle d'événements
+  « non mesurée » plutôt que d'afficher un zéro trompeur.
+
+### Obtenir le porteur — `security:mcp:token`
 
 Dès que la porte demande un jeton, il faut en produire un. L'application **le signe elle-même**, en
 ligne de commande, sans qu'aucun serveur n'écoute :
 
 ```bash
-npx nodefony security:token --write   # pose NF_MCP_TOKEN chez les agents présents
+npx nodefony security:mcp:token --write   # pose NF_MCP_TOKEN chez les agents présents
 npx nodefony ai:mcp --auth            # l'en-tête porte ${NF_MCP_TOKEN}, jamais le jeton
 ```
 
@@ -203,7 +335,8 @@ métier — et c'est précisément ce qu'un agent invente le plus mal. N'importe
 module de votre application peut donc en publier :
 
 ```ts
-import { Module, mcpText, type IMcpTool } from "nodefony";
+import { Module, type IMcpTool } from "nodefony";
+import { mcpText } from "@nodefony/ai";
 
 class Shop extends Module {
   getMcpTools(): IMcpTool[] {
@@ -221,6 +354,10 @@ class Shop extends Module {
           properties: { sku: { type: "string", description: "Référence" } },
           required: ["sku"],
         },
+        // Il LIT la base et ne sort pas de l'application : il le dit, sinon la
+        // spec le tient pour destructif et l'agent demande confirmation à
+        // chaque lecture.
+        annotations: { readOnlyHint: true, openWorldHint: false },
         handler: async (args) => mcpText(await this.stock(String(args.sku))),
       },
     ];
@@ -228,8 +365,14 @@ class Shop extends Module {
 }
 ```
 
-Trois choses à savoir :
+Quatre choses à savoir :
 
+- **un outil dit ce qu'il fait** (`annotations`, indices `ToolAnnotations` de la
+  spec MCP) : sans annotation, la spec le tient pour un outil qui écrit, détruit
+  et sort de l'application. Un outil qui lit se déclare `readOnlyHint: true` ;
+  un outil qui modifie, `readOnlyHint: false`. Un indice n'est jamais une
+  autorisation — le détail des cinq indices et de leurs défauts :
+  [écrire un outil](../../ai/docs/mcp.md#dire-ce-que-fait-loutil--les-annotations) ;
 - **rien ne s'enregistre au démarrage** : la liste est relue à chaque requête,
   donc un module ajouté apparaît sans redémarrer quoi que ce soit ;
 - **`mcp.tools` ne filtre que les outils intégrés** — le vôtre est publié dès
@@ -280,7 +423,9 @@ est absent de `tools/list` **et** inappelable en le nommant, et le refus dit
 ### Un outil LONG — progression et annulation
 
 Le troisième paramètre du handler sert l'outil qui dure : `run.signal` est
-abattu quand l'agent abandonne l'appel, `run.progress()` lui donne signe de vie.
+abattu quand le client annule — qu'il ferme le flux de la réponse (révision courante
+de MCP) ou envoie `notifications/cancelled` (révision précédente) —,
+`run.progress()` lui donne signe de vie.
 Un outil court l'ignore ; un appel direct (un test) ne le fournit pas, d'où le
 `run?.` :
 
@@ -303,10 +448,14 @@ Un outil court l'ignore ; un appel direct (un test) ne le fournit pas, d'où le
 
 Ce que la porte fait du reste :
 
-- **le flux ne s'ouvre qu'à la première progression.** Un agent qui envoie un
-  `progressToken` et accepte `text/event-stream` reçoit des
-  `notifications/progress`, puis la réponse, qui clôt le flux. Sans jeton, ou
-  pour un outil qui ne signale rien, la réponse reste du JSON ;
+- **le flux s'ouvre à la première progression, ou au bout de cinq secondes.**
+  Un agent qui envoie un `progressToken` et accepte `text/event-stream` reçoit
+  des `notifications/progress`, puis la réponse, qui clôt le flux. Un outil
+  encore en cours après le délai de grâce (`MCP_STREAM_GRACE_MS`, 5 s) ouvre le
+  flux même sans jeton : la norme oblige le client à accepter une réponse en
+  flux, et c'est ce qui désarme le délai d'inactivité de la requête (30 s par
+  défaut) — sans cela, un outil long répondant en JSON recevrait un `408`. Un
+  outil qui répond avant reste en JSON ;
 - **la norme est tenue pour vous** : une valeur qui ne croît pas est ignorée, la
   cadence est bornée (une notification par 100 ms au plus), et plus rien ne
   part une fois l'outil terminé ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/devkit",
-  "version": "10.0.0-beta.3",
+  "version": "10.0.0-beta.4",
   "type": "module",
   "description": "Outillage de développement d'une application Nodefony : carte de visite du projet et portes de découverte pour un agent de développement",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
@@ -20,22 +20,27 @@
   ],
   "scripts": {
     "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
+    "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "typecheck": "tsgo --noEmit -p tsconfig.json && tsgo --noEmit -p tsconfig.tests.json",
     "test": "vitest run",
-    "coverage": "vitest run --coverage"
+    "coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.3",
-    "@nodefony/http": "^10.0.0-beta.3",
-    "nodefony": "^10.0.0-beta.3",
-    "zod": "^4.6.7",
+    "@nodefony/ai": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.4",
+    "@nodefony/http": "^10.0.0-beta.4",
+    "lighthouse": "^13.0.0",
+    "nodefony": "^10.0.0-beta.4",
     "playwright": "^1.50.0",
-    "lighthouse": "^13.0.0"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.3",
-    "@nodefony/http": "^10.0.0-beta.3",
-    "nodefony": "^10.0.0-beta.3"
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@nodefony/ai": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.4",
+    "@nodefony/http": "^10.0.0-beta.4",
+    "nodefony": "^10.0.0-beta.4"
   },
   "dependencies": {
     "axe-core": "4.14.0",
@@ -72,6 +77,6 @@
     "esm"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.14.0"
   }
 }