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

package/dist/nodefony/service/DevkitService.js

@@ -1,15 +1,20 @@
+import { asProfilerReader } from "../mcp/observe.js";
+import { readShotTarget } from "../mcp/shotClient.js";
+import { PROFILE_SESSION_FACTOR } from "../src/profileSession.js";
+import { selectBuiltinMcpTools } from "../mcp/tools.js";
 import defaults from "../config/config.js";
 import { buildCard } from "../src/card.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
-import { Module, Nodefony, Service, extend, injectable, mcpDeclaredScopes } from "nodefony";
-//#region nodefony/service/DevkitService.ts
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
+import { ADMIN_DEFAULT_ROLE, Nodefony, ROLES_WITHIN, Service, extend, injectable } from "nodefony";
+import { defineMcpGate, defineTicketSessionGate, mcpDeclaredScopes } from "@nodefony/ai";
+// nodefony/service/DevkitService.ts
 /**
-* Réponse partagée quand la porte MCP n'est pas protégée — le cas par défaut.
-* Allouer un tableau vide pour dire « rien » est la dépense que la règle de
-* lazy-allocation proscrit.
+* Ce que l'agent lit en arrivant sur la porte de développement — la phrase
+* d'ouverture des `instructions`, suivie par le moteur des outils servis.
 */
-const EMPTY_PROTECTED_RESOURCES = Object.freeze([]);
+const DEVKIT_MCP_INSTRUCTIONS = "Outils d'introspection d'une application Nodefony — ils répondent depuis l'application qui TOURNE, pas depuis une lecture des sources. Commence par la carte de visite si tu arrives sur cette application. Pour MESURER plutôt que lire le code — une page lente, trop de requêtes SQL, l'effet d'une modification — nodefony_profile_route tire lui-même N requêtes sur un chemin et rend son profil ; nodefony_observe mesure le trafic que tu génères (tests, navigation). Avant d'écrire un script de banc.";
+/** Ce qu'accorde la porte de développement à qui l'atteint sans jeton. */
+const DEV_OPERATOR_ROLES = [ADMIN_DEFAULT_ROLE];
 /**
 * Service principal du module — la logique vit ici, pas dans les controllers
 * (un controller traduit du HTTP/WS ; un service, lui, est réutilisable par la
@@ -20,7 +25,7 @@ const EMPTY_PROTECTED_RESOURCES = Object.freeze([]);
 *
 * 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.
@@ -36,13 +41,13 @@ const EMPTY_PROTECTED_RESOURCES = Object.freeze([]);
 * ```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);
 *   }
@@ -56,6 +61,10 @@ const EMPTY_PROTECTED_RESOURCES = Object.freeze([]);
 let DevkitService = class DevkitService extends Service {
 	module;
 	cfg;
+	/** La porte MCP de développement — définie au premier usage (`mcpGate()`). */
+	#mcpGate = null;
+	/** La porte de session du profilage — définie au premier usage (`profileSessionGate()`). */
+	#profileSessionGate = null;
 	constructor(module) {
 		const options = module.options;
 		const merged = extend(true, {}, defaults, options ?? {});
@@ -130,10 +139,37 @@ let DevkitService = class DevkitService extends Service {
 		return {
 			broker: this.get("adminBroker") ?? void 0,
 			getCard: () => this.getCard(),
-			projectRoot: kernel?.path ?? process.cwd()
+			projectRoot: kernel?.path ?? process.cwd(),
+			getProfiler: () => asProfilerReader(this.get("profiler")),
+			servesTraffic: () => kernel?.runProfile.servers === true,
+			onShutdown: (listener) => {
+				if (kernel === null) return () => {};
+				kernel.prependOnceListener("onTerminate", listener);
+				return () => {
+					kernel.removeListener("onTerminate", listener);
+				};
+			},
+			profileRoute: {
+				getTarget: () => readShotTarget(this.get("server-http")),
+				issueTicket: (identifier) => this.profileSessionGate().issue(identifier),
+				closeSession: async (ref) => this.profileSessionGate().close(this.get("sessions"), ref),
+				rolesWithin: this.get(ROLES_WITHIN) ?? void 0
+			}
 		};
 	}
 	/**
+	* 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() {
+		return selectBuiltinMcpTools(this.cfg.mcp.tools, this.mcpToolDeps());
+	}
+	/**
 	* Les scopes que la porte MCP EXIGE — dérivés des outils qu'elle déclare.
 	*
 	* 🔴 **Aucune liste de configuration ne double celle-ci**, et c'est la
@@ -149,11 +185,7 @@ let DevkitService = class DevkitService extends Service {
 	* @returns les scopes dédupliqués et triés
 	*/
 	declaredMcpScopes() {
-		return mcpDeclaredScopes({
-			builtins: this.cfg.mcp.tools,
-			deps: this.mcpToolDeps(),
-			modules: this.module.kernel?.modules
-		});
+		return mcpDeclaredScopes({ modules: this.module.kernel?.modules });
 	}
 	/**
 	* Ce que ce module protège, à publier en RFC 9728 — la porte MCP, ou rien.
@@ -178,22 +210,54 @@ let DevkitService = class DevkitService extends Service {
 	* @returns une entrée pour la porte MCP, ou aucune
 	*/
 	publishedProtectedResources() {
-		const mcp = this.cfg.mcp;
-		const authz = mcp.authorization;
-		if (!mcp.enabled || authz.authorizationServers.length === 0) return EMPTY_PROTECTED_RESOURCES;
-		return [{
-			resource: authz.resource,
-			authorizationServers: authz.authorizationServers,
-			scopesSupported: this.declaredMcpScopes(),
-			resourceName: authz.resourceName,
-			resourceDocumentation: authz.resourceDocumentation
-		}];
+		return this.mcpGate().protectedResources(this.module.kernel?.modules);
+	}
+	/**
+	* 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() {
+		if (this.#mcpGate === null) {
+			const mcp = this.cfg.mcp;
+			const gateProtected = mcp.authorization.authorizationServers.length > 0;
+			this.#mcpGate = defineMcpGate({
+				enabled: mcp.enabled,
+				allowedOrigins: mcp.allowedOrigins,
+				allowRemote: mcp.allowRemote,
+				authorization: mcp.authorization,
+				tools: "modules",
+				instructions: DEVKIT_MCP_INSTRUCTIONS,
+				unprotectedRoles: gateProtected ? [] : [...DEV_OPERATOR_ROLES]
+			});
+		}
+		return this.#mcpGate;
+	}
+	/**
+	* 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() {
+		this.#profileSessionGate ??= defineTicketSessionGate({ factor: PROFILE_SESSION_FACTOR });
+		return this.#profileSessionGate;
 	}
 	status() {
 		return { ready: this.cfg.enabled };
 	}
 };
-DevkitService = __decorate([injectable(), __decorateMetadata("design:paramtypes", [typeof Module === "undefined" ? Object : Module])], DevkitService);
+DevkitService = __decorate([injectable()], DevkitService);
 var DevkitService_default = DevkitService;
-//#endregion
 export { DevkitService_default as default };

package/dist/nodefony/src/card.js

@@ -1,2 +1 @@
-import { buildCard, renderCard } from "nodefony";
-export { buildCard, renderCard };
+export { buildCard, renderCard } from "nodefony";

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/errors/DevkitError.ts
+// nodefony/src/errors/DevkitError.ts
 /**
 * Erreur du module devkit.
 *
@@ -17,5 +17,4 @@ var DevkitError = class extends Error {
 		this.name = "DevkitError";
 	}
 };
-//#endregion
 export { DevkitError, DevkitError as default };

package/dist/nodefony/src/profileSession.js

@@ -0,0 +1,14 @@
+// nodefony/src/profileSession.ts
+/**
+* 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.
+*/
+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é.
+*/
+const PROFILE_SESSION_PATH = "/nodefony/devkit/profile-session";
+export { PROFILE_SESSION_FACTOR, PROFILE_SESSION_PATH };

package/dist/types/index.d.ts

@@ -1,8 +1,10 @@
 import { Kernel, Module } from "nodefony";
+import type { IMcpTool } from "nodefony";
 import { type IDevkitConfigInput } from "./nodefony/config/config.js";
 import DevkitService from "./nodefony/service/DevkitService.js";
 import DevkitController from "./nodefony/controllers/DevkitController.js";
 import McpController from "./nodefony/controllers/McpController.js";
+import ProfileSessionController from "./nodefony/controllers/ProfileSessionController.js";
 /**
  * @nodefony/devkit — Outillage de developpement d une application Nodefony : carte de visite et portes de decouverte pour un agent
  *
@@ -43,9 +45,21 @@ declare class DevkitModule extends Module {
      * fautif nommé, plutôt qu'en `undefined.x` au premier appel en production.
      */
     onKernelRegister(): Promise<this>;
+    /**
+     * Déclare les outils `nodefony_*` — comme n'importe quel module.
+     *
+     * Aucun cas particulier côté collecte : `@nodefony/ai` les ramasse avec ceux
+     * de l'application, et seul le préfixe `nodefony_`, réservé aux modules
+     * `@nodefony/*`, les distingue. Un service absent (module en cours de
+     * démontage) ne déclare rien plutôt que de lever.
+     *
+     * @returns les outils retenus par l'allowlist `mcp.tools`
+     */
+    getMcpTools(): IMcpTool[];
 }
 export default DevkitModule;
-export { DevkitService, DevkitController, McpController };
+export { DevkitService, DevkitController, McpController, ProfileSessionController, };
+export { builtinMcpTools, selectBuiltinMcpTools, BUILTIN_MCP_TOOL_KEYS, type BuiltinMcpToolKey, type IMcpToolDeps, } from "./nodefony/mcp/tools.js";
 export { buildCard } from "./nodefony/src/card.js";
 export { defineDevkitConfig } from "./nodefony/config/defineModuleConfig.js";
 export { devkitConfigSchema, type IDevkitConfig, type IDevkitConfigInput, } from "./nodefony/config/config.js";

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

@@ -5,7 +5,6 @@ export declare const devkitConfigSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
         allowRemote: z.ZodDefault<z.ZodBoolean>;
-        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
         authorization: z.ZodDefault<z.ZodObject<{
             authorizationServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
             resource: z.ZodDefault<z.ZodString>;
@@ -14,6 +13,7 @@ export declare const devkitConfigSchema: z.ZodObject<{
             resourceDocumentation: z.ZodOptional<z.ZodString>;
             anonymous: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Config telle que l'APP l'écrit dans `use()` — tous les champs optionnels. */

package/dist/types/nodefony/controllers/McpController.d.ts

@@ -1,8 +1,8 @@
 import { Controller } from "@nodefony/framework";
 import type { ContextType } from "@nodefony/http";
 /**
- * Serveur **Model Context Protocol** de l'application — la porte par laquelle
- * un agent externe l'interroge.
+ * Porte **Model Context Protocol** de DÉVELOPPEMENT — celle par laquelle
+ * l'agent de code du développeur interroge l'application.
  *
  * ## Pourquoi une route, et pas un process
  *
@@ -19,7 +19,7 @@ import type { ContextType } from "@nodefony/http";
  *
  * **Par défaut, le périmètre — et lui seul.** Ce module est `policy: "dev"`,
  * donc cette route n'existe pas en production ; restent les deux gardes que la
- * spec impose au transport, portées par {@link checkMcpAccess} : l'en-tête
+ * spec impose au transport (`checkMcpAccess`, `@nodefony/ai`) : l'en-tête
  * `Origin` et la localité de l'appelant. Elles visent le seul vecteur réel
  * contre un serveur local — une page web ouverte dans le navigateur du
  * développeur.
@@ -46,25 +46,21 @@ import type { ContextType } from "@nodefony/http";
  * Rôle déclaré + aucun vérificateur = `503` et journal `CRITIC`, jamais une
  * porte qui laisse passer les porteurs sans les lire.
  *
- * **Mince par design** : tout le protocole vit AU CŒUR (`nodefony`, en fonctions
- * pures) ; ce controller ne fait que traduire HTTP ↔ JSON-RPC et fournir au
- * collecteur ce que lui seul connaît — le service du module, le broker
- * d'administration, la racine du projet. C'est ce qui permet à un autre module
- * d'ouvrir la même porte ailleurs (en production, sous authentification) sans
- * réécrire une ligne de protocole.
+ * **Mince par design** : la porte est définie par `defineMcpGate` (`@nodefony/ai`)
+ * dans `DevkitService.mcpGate()`, à partir de `devkit.mcp.*` ; ce controller
+ * ne fait que la servir. Une application ouvre SA porte, en développement ou en
+ * production, exactement de la même façon.
  */
 declare class McpController extends Controller {
     #private;
     constructor(context: ContextType);
     /**
-     * `POST /nodefony/mcp` — un message JSON-RPC entre, une réponse sort.
-     *
-     * Les trois statuts que rend cette route sont ceux que la spec impose, et pas
-     * un de plus : `202` sans corps pour une notification acceptée, `403` pour un
-     * appel dont l'origine ou l'adresse est refusée, `404` pour une méthode
-     * inconnue (afin de la distinguer d'un serveur qui n'hébergerait pas
-     * d'endpoint MCP du tout).
+     * `/nodefony/mcp` — `POST` sert un message JSON-RPC ; `GET` et `DELETE`
+     * rendent `405` + `Allow: POST` (verbes retirés par la révision
+     * `2026-07-28`). Sans eux, la requête tombait dans le repli SPA du Studio
+     * (`/nodefony/{page}`) : `200` + HTML, que le client prenait pour un flux
+     * rompu et rouvrait à chaque seconde, indéfiniment.
      */
-    mcp(body: unknown, origin?: string, protocolVersion?: string, authorization?: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    mcp(body: unknown): Promise<unknown>;
 }
 export default McpController;

package/dist/types/nodefony/controllers/ProfileSessionController.d.ts

@@ -0,0 +1,31 @@
+import { Controller } from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+/**
+ * Ouvre la session au nom de laquelle `nodefony_profile_route` tire ses
+ * requêtes.
+ *
+ * **Mince par design** : la mécanique (ticket à usage unique, localité,
+ * ouverture par le flux de session de l'application, verdict uniforme) est la
+ * porte `defineTicketSessionGate` de `@nodefony/ai`, définie dans
+ * `DevkitService.profileSessionGate()`. Ce controller ne fait que DÉCLARER la
+ * route, comme le ferait une application pour ses propres outils.
+ *
+ * Ce qui protège cette route : le ticket (émis dans le process, valable dix
+ * secondes, jamais affiché ni journalisé, identité fixée à l'émission), la
+ * localité de l'appelant (défaut de la porte), et la `policy: "dev"` du module.
+ *
+ * Elle vit sous `/nodefony/devkit/`, hors du motif de la zone d'administration
+ * (`^/nodefony/[^/]+/api`), qui exigerait une session déjà ouverte.
+ */
+declare class ProfileSessionController extends Controller {
+    #private;
+    constructor(context: ContextType);
+    /**
+     * `POST /nodefony/devkit/profile-session` — rachète le ticket et ouvre la
+     * session. `200` rend le compte et le pseudonyme de session ; tout refus est
+     * un `403` au message unique ; `503` quand l'application n'a pas de flux de
+     * session.
+     */
+    profileSession(): Promise<unknown>;
+}
+export default ProfileSessionController;

package/dist/types/nodefony/interfaces/IDevkitService.d.ts

@@ -1,4 +1,6 @@
-import type { ICard, ICardAppInfo, ICardDoor, ICardInput, ICardVerb, IMcpToolDeps } from "nodefony";
+import type { IMcpGate, ITicketSessionGate } from "@nodefony/ai";
+import type { ICard, ICardAppInfo, ICardDoor, ICardInput, ICardVerb, IMcpTool } from "nodefony";
+import type { IMcpToolDeps } from "../mcp/tools.js";
 import type { IDevkitConfig } from "../config/config.js";
 /**
  * Le contrat de la carte est celui du CŒUR — ces noms n'en sont que les alias,
@@ -58,6 +60,11 @@ export interface IDevkitService {
      * dont sont dérivés les scopes publiés.
      */
     mcpToolDeps(): IMcpToolDeps;
+    /**
+     * Les outils `nodefony_*` que l'allowlist `mcp.tools` retient — ceux que le
+     * module déclare par `getMcpTools()`.
+     */
+    mcpTools(): IMcpTool[];
     /**
      * Les scopes que la porte MCP EXIGE, dérivés des outils déclarés.
      *
@@ -66,4 +73,18 @@ export interface IDevkitService {
      * n'exige rien, et le champ est alors omis du document.
      */
     declaredMcpScopes(): readonly string[];
+    /**
+     * La porte MCP de développement (`POST /nodefony/mcp`), bâtie sur
+     * `defineMcpGate` à partir de `devkit.mcp.*` — définie une fois, au premier usage.
+     */
+    mcpGate(): IMcpGate;
+    /**
+     * La porte de session du profilage (`POST /nodefony/devkit/profile-session`),
+     * bâtie sur `defineTicketSessionGate` — définie une fois, au premier usage.
+     *
+     * L'outil de profilage y émet le ticket qui ouvrira SA session ; la route la
+     * sert. Le magasin de tickets n'est alloué qu'au premier ticket émis : une
+     * requête reçue n'alloue rien.
+     */
+    profileSessionGate(): ITicketSessionGate;
 }

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

@@ -0,0 +1,83 @@
+import { type IMcpCaller, type IMcpTool } from "nodefony";
+import { type IProfilerReader } from "@nodefony/http";
+import { type RequestLogs } from "./profileReport.js";
+import { type OnShutdown } from "./shutdown.js";
+/** Fenêtre d'observation par défaut, en secondes. */
+export declare const OBSERVE_DEFAULT_SEC = 10;
+/**
+ * Fenêtre maximale, en secondes. Sous les 60 s qu'un client MCP attend par
+ * défaut avant d'abandonner une requête : au-delà, l'agent couperait l'appel
+ * juste avant le rapport.
+ */
+export declare const OBSERVE_MAX_SEC = 50;
+/** Intervalle entre deux relevés, en ms : un instantané de progression par relevé. */
+export declare const OBSERVE_TICK_MS = 2000;
+/**
+ * Requêtes en erreur dont on lit le journal, au plus — les mêmes que les
+ * exemples d'erreurs du rapport, dans le même ordre.
+ */
+export declare const OBSERVE_ERROR_LOGS_MAX = 10;
+/** La sonde du process : ce que l'outil lit du process à chaque relevé. */
+export interface IObserveProbe {
+    read(): {
+        eventLoopMs: number;
+        eventLoopMaxMs: number;
+        heapUsed: number;
+    };
+    dispose(): void;
+}
+/**
+ * Ce que rend un outil de MESURE dans un process qui ne sert aucune requête —
+ * l'application démarrée en console, sous la porte stdio (`nodefony ai:stdio`).
+ * Sans ce refus, `nodefony_observe` y attendrait un trafic qui n'arrive jamais
+ * et rendrait « aucune requête » avec aplomb.
+ */
+export declare const NOT_SERVING_MESSAGE: string;
+/** Ce dont l'outil a besoin — injecté, pour l'éprouver sans application. */
+export interface IObserveDeps {
+    /** Le profileur de l'application, ou `undefined` (production, `@nodefony/http` absent). */
+    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;
+    /** Intervalle entre deux relevés (défaut {@link OBSERVE_TICK_MS}). */
+    tickMs?: number | undefined;
+    /** Fabrique de la sonde du process (défaut : `ProcessProbe` du cœur). */
+    createProbe?: (() => IObserveProbe) | undefined;
+    /**
+     * Lit les lignes de journal d'une requête (syslog de l'application, par
+     * `requestId`). Absent : le rapport renvoie à `nodefony_admin_call`.
+     */
+    readRequestLogs?: ((requestId: string, caller: IMcpCaller) => Promise<RequestLogs>) | undefined;
+    /**
+     * S'abonne à l'arrêt du serveur pour la durée d'UN appel, et rend de quoi
+     * se désabonner. L'arrêt attend la promesse de l'écouteur (bornée) : le
+     * temps que le rapport partiel parte.
+     */
+    onShutdown?: OnShutdown | undefined;
+}
+/**
+ * Reconnaît un profileur par sa FORME : le conteneur le rend sous le nom
+ * `"profiler"`, et ce module ne dépend pas de sa classe.
+ *
+ * @param value - ce que le conteneur a rendu.
+ * @returns le lecteur, ou `undefined` s'il ne tient pas le contrat.
+ */
+export declare function asProfilerReader(value: unknown): IProfilerReader | undefined;
+/**
+ * L'outil `nodefony_observe` : observe l'application qui tourne pendant une
+ * fenêtre bornée et rend ce que le profileur de développement a mesuré —
+ * routes lentes et où part leur temps, N+1, requêtes SQL coûteuses, erreurs,
+ * charge du process.
+ *
+ * C'est un outil LONG : un relevé toutes les deux secondes, chacun envoyé à
+ * l'agent en progression ; un client qui l'annule l'arrête au relevé suivant,
+ * qu'il ferme le flux de la réponse ou envoie `notifications/cancelled`. Rien
+ * n'est armé en dehors d'un appel : un minuteur par relevé,
+ * libéré par l'annulation elle-même, et la sonde du process libérée en sortie.
+ *
+ * @param deps - le profileur et, pour les tests, la cadence et la sonde.
+ */
+export declare function observeTool(deps: IObserveDeps): IMcpTool;

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

@@ -0,0 +1,138 @@
+import { type IProfileReport } from "@nodefony/http";
+/**
+ * Le rapport de profil tel qu'un AGENT de code le lit — rendu partagé par les
+ * outils qui observent l'application (`nodefony_observe`) ou la sollicitent.
+ *
+ * L'ordre est celui de la décision : un verdict d'abord, puis ce qu'il faut
+ * corriger (une anomalie par ligne, nommée par route, contrôleur et forme SQL),
+ * les tableaux ensuite, et les données brutes en dernier pour comparer deux
+ * appels. Chaque section est bornée : le texte entier reste sous la limite que
+ * la porte impose à une réponse d'outil.
+ */
+/** p95 à partir duquel une route est signalée lente (développement, machine locale). */
+export declare const SLOW_ROUTE_P95_MS = 500;
+/**
+ * Pire blocage de la boucle d'événements à partir duquel on le signale : au-delà,
+ * TOUTES les requêtes en cours ont attendu, quelle que soit leur route.
+ */
+export declare const EVENT_LOOP_BLOCK_MS = 100;
+/** Les lignes de journal d'une requête, ou la raison pour laquelle on ne les a pas. */
+export type RequestLogs = {
+    kind: "lines";
+    lines: string[];
+    /** Lignes lues mais écartées (détail sous WARNING, ou au-delà du plafond). */
+    hidden?: number | undefined;
+} | {
+    kind: "unavailable";
+    reason: string;
+};
+/** Au nom de qui les requêtes d'un tir ont été jouées. */
+export type ShotIdentity = {
+    kind: "anonymous";
+    /** Pourquoi aucun compte n'a été joué ; `null` quand l'appelant l'a demandé. */
+    why: string | null;
+} | {
+    kind: "account";
+    identifier: string;
+    roles: readonly string[];
+    /** Un autre compte que le propriétaire du jeton (`as`). */
+    impersonated: boolean;
+};
+/** Ce que le client du tir a reçu, statut par statut. */
+export interface IShotClientStatus {
+    ok: number;
+    redirected: number;
+    unauthorized: number;
+    forbidden: number;
+    clientError: number;
+    serverError: number;
+    /** Requêtes sans réponse (connexion refusée, délai dépassé). */
+    failed: number;
+    /** Première destination de redirection reçue. */
+    location: string | null;
+    /** Première erreur réseau reçue. */
+    failure: string | null;
+}
+/**
+ * Le tir de `nodefony_profile_route` : ce que l'outil a envoyé, au nom de qui,
+ * et ce que son client a reçu. Absent pour `nodefony_observe`, qui n'envoie rien.
+ */
+export interface IShotSummary {
+    method: "GET" | "HEAD";
+    path: string;
+    requested: number;
+    sent: number;
+    concurrency: number;
+    identity: ShotIdentity;
+    /** Lot de chauffe, tiré AVANT et hors des mesures. */
+    warmup: {
+        count: number;
+        p50Ms: number | null;
+        maxMs: number | null;
+    };
+    client: IShotClientStatus;
+    /** Réponses reçues dont le profil n'a pas été retrouvé. */
+    missing: number;
+    /** Tir arrêté faute de temps, avant d'avoir tout envoyé. */
+    truncated: boolean;
+    /** Budget de temps du tir, en ms. */
+    budgetMs: number;
+}
+/** Le déroulé de l'observation : ce que le rapport doit dire de sa propre fiabilité. */
+export interface IObservationContext {
+    /** Fenêtre demandée, en ms. */
+    windowMs: number;
+    /** Durée réellement observée, en ms. */
+    elapsedMs: number;
+    /** Relevés effectués. */
+    ticks: number;
+    /** Profils disparus avant d'être lus (tampon débordé, identifiant réutilisé). */
+    lost: number;
+    /** L'agent a abandonné l'appel avant la fin de la fenêtre. */
+    cancelled: boolean;
+    /** Le serveur s'est arrêté pendant la fenêtre (rechargement, arrêt). */
+    interrupted: boolean;
+    /**
+     * Journal des requêtes en erreur, lu au relevé qui les a vues ; `null` quand
+     * l'outil n'a pas de quoi le lire.
+     */
+    errorLogs: ReadonlyMap<string, RequestLogs> | null;
+    /** Route à laquelle l'observation était restreinte, s'il y en avait une. */
+    route: string | null;
+    /** Requêtes écartées par ce filtre de route. */
+    filteredRoute: number;
+    pid: number;
+    uptimeSec: number;
+    /**
+     * Retard de la boucle d'événements sur la fenêtre (ms), si mesuré : moyen,
+     * et pire blocage (qu'une moyenne noie).
+     */
+    eventLoop: {
+        meanMs: number;
+        maxMs: number;
+    } | null;
+    /**
+     * Variation du tas sur la fenêtre (octets), si mesurée — sans GC forcé : du
+     * déchet en attente autant que de la rétention, donc indicative.
+     */
+    heapDeltaBytes: number | null;
+    /** Le tir, quand c'est l'outil qui a envoyé les requêtes. */
+    shot?: IShotSummary | undefined;
+}
+/**
+ * Rend le rapport complet pour l'agent.
+ *
+ * @param report - l'agrégation des profils observés.
+ * @param ctx - le déroulé de l'observation.
+ * @returns le texte, borné.
+ */
+export declare function renderProfileReport(report: IProfileReport, ctx: IObservationContext): string;
+/**
+ * La ligne d'un relevé intermédiaire, envoyée en progression à l'agent.
+ *
+ * @param report - l'agrégation à cet instant.
+ * @param elapsedSec - secondes écoulées.
+ * @param windowSec - fenêtre demandée.
+ * @param lost - profils perdus jusqu'ici.
+ */
+export declare function progressLine(report: IProfileReport, elapsedSec: number, windowSec: number, lost: number): string;