@imenam/mcp-messenger 1.0.3 → 1.0.4

package/README.md

@@ -143,11 +143,25 @@ n'hérite pas du bloc `env` du `.mcp.json`, donc ni de `MESSENGER_SERVER_URL` ni
 Le fichier est nommé par hachage de l'adresse, supprimé à la fin de la session, et purgé au
 bout de sept jours si la session s'est arrêtée brutalement.
 
+**Savoir si c'est vraiment armé.** L'armement dépend de l'agent : rien ne peut le déclencher
+à sa place, et un agent qui saute l'étape se croirait joignable sans l'être. Le serveur suit
+donc les attentes tenues par un veilleur, et `whoami` le dit :
+
+```
+Notifications: armed — incoming messages will interrupt you (watcher since 2026-09-07T13:31:00.203Z).
+Notifications: NOT armed — no incoming message will reach you. Call enable_notifications.
+```
+
+C'est une présence de connexion, pas une donnée stockée : elle vit en mémoire du serveur et
+disparaît avec lui. Un `wait_for_message` ordinaire ne compte pas — il s'arrête au premier
+message, un veilleur reste. Entre deux attentes longues, un délai de grâce de deux minutes
+évite que le signalement clignote. `enable_notifications` s'en sert aussi : si un veilleur est
+déjà en place, il le dit et n'en fait pas armer un second, qui doublerait chaque notification.
+
 **Ce que ça ne couvre pas.** Le veilleur n'annonce que les messages arrivés **après** son
 démarrage : `enable_notifications` signale le nombre de non-lus déjà en boîte, à traiter avec
-`list_messages`. Et l'armement dépend de l'agent : s'il saute l'étape `Monitor`, il ne sera
-jamais notifié et rien côté serveur ne le détecte. C'est pourquoi `--claude-setup-mcp` écrit
-un rappel dans le `CLAUDE.md` du projet.
+`list_messages`. Et `--claude-setup-mcp` écrit un rappel d'armement dans le `CLAUDE.md` du
+projet, pour que l'étape ne soit pas oubliée en début de session.
 
 **Sur un autre hôte que Claude Code.** `--watch` est une commande ordinaire : n'importe quel
 superviseur capable de lire les lignes d'un processus peut la brancher. Sans relais, elle lit
@@ -159,7 +173,7 @@ superviseur capable de lire les lignes d'un processus peut la brancher. Sans rel
 
 | Outil | Rôle |
 |---|---|
-| `whoami` | Adresse de cette session, serveur connecté, compteurs par dossier |
+| `whoami` | Adresse de cette session, serveur connecté, veilleur armé ou non, compteurs par dossier |
 | `attach_to_mailbox` | Se brancher sur une autre boîte via son adresse ; sans argument, retour à la sienne |
 | `set_mailbox_label` | Nommer sa boîte, pour la reconnaître dans l'annuaire et la console |
 | `list_agents` | Annuaire : qui est joignable, avec quelle description |
@@ -298,7 +312,7 @@ cet agent lorsque `MESSENGER_AGENT_TOKENS` est utilisé.
 | `GET` | `/api/agents` | Annuaire des boîtes |
 | `GET` | `/api/agents/:id` | Une boîte, ou 404 |
 | `PATCH` | `/api/agents/me` | Renommer la boîte courante |
-| `GET` | `/api/mailbox` | Compteurs de la boîte |
+| `GET` | `/api/mailbox` | Compteurs de la boîte, et présence d'un veilleur (`watcher`) |
 | `POST` | `/api/messages` | Envoyer un message |
 | `GET` | `/api/messages` | Lister (`folder`, `unread_only`, `from`, `thread_id`, `search`, `limit`, `offset`) |
 | `GET` | `/api/messages/:id` | Lire (`?mark_read=false` pour ne pas marquer) |
@@ -307,7 +321,7 @@ cet agent lorsque `MESSENGER_AGENT_TOKENS` est utilisé.
 | `POST` | `/api/messages/delete` | Corbeille ou suppression définitive |
 | `GET` | `/api/threads/:id` | Fil complet |
 | `GET` `POST` `DELETE` | `/api/folders[/:name]` | Gérer les dossiers |
-| `GET` | `/api/wait` | Attente longue (`timeout_seconds`, `folder`) |
+| `GET` | `/api/wait` | Attente longue (`timeout_seconds`, `folder`, `watcher`) |
 | `GET` | `/admin/overview` · `/admin/messages[/:id]` · `/admin/threads/:id` | Supervision, lecture seule |
 
 ---
@@ -355,6 +369,7 @@ src/
   logger.ts             # journalisation sur stderr (stdout est réservé au JSON-RPC)
   core/store.ts         # SQLite : agents, messages, livraisons, dossiers
   server/app.ts         # API HTTP, authentification, supervision
+  server/watchers.ts    # présence des veilleurs, en mémoire : état de connexion
   server/start.ts       # démarrage, arrêt propre, purge de la corbeille
   server/ui/            # console web (HTML/CSS/JS sans dépendance)
   cli/watch.ts          # mode veilleur : une ligne sur stdout par message entrant
@@ -366,7 +381,7 @@ test/                   # store, config, API HTTP, outils MCP, binaire réel
 
 ### Tests
 
-104 tests couvrant : le stockage et l'isolation des boîtes, la validation de configuration,
+112 tests couvrant : le stockage et l'isolation des boîtes, la validation de configuration,
 l'API HTTP et son authentification (refus systématique sans jeton, jeton partagé, jetons par
 agent, jeton de console distinct), les outils MCP de bout en bout (deux agents qui
 conversent à travers un vrai serveur), l'allocation des boîtes par session — deux processus
@@ -376,7 +391,8 @@ troisième session reprend la boîte de l'une d'elles — et le binaire publié
 La notification passive est couverte de bout en bout : le relais vers le veilleur (isolation
 entre boîtes, adresse jamais transformée en chemin, nettoyage), le format d'évènement (une
 ligne, quel que soit le sujet), et un veilleur réellement lancé comme processus séparé, sans
-jeton dans son environnement, qui émet sa ligne à l'arrivée d'un message.
+jeton dans son environnement, qui émet sa ligne à l'arrivée d'un message — et `whoami` qui
+passe de « NOT armed » à « armed » quand ce veilleur prend son poste.
 
 ---
 

package/dist/src/cli/watch.js

@@ -63,7 +63,7 @@ export async function runWatchMode(mailbox) {
     let backoff = BACKOFF_MIN_MS;
     for (;;) {
         try {
-            const result = await client.waitForMessage(POLL_SECONDS);
+            const result = await client.waitForMessage(POLL_SECONDS, undefined, { watcher: true });
             backoff = BACKOFF_MIN_MS;
             if (result.timed_out || !result.message)
                 continue;

package/dist/src/client/messenger-client.d.ts

@@ -80,6 +80,13 @@ export declare class MessengerClient {
     listFolders(): Promise<FolderInfo[]>;
     createFolder(name: string): Promise<FolderInfo>;
     deleteFolder(name: string): Promise<number>;
-    waitForMessage(timeoutSeconds: number, folder?: string): Promise<WaitResult>;
+    /**
+     * `watcher` signale une attente tenue par un veilleur `--watch`, et non par un
+     * `wait_for_message` ponctuel : c'est ce qui permet au serveur de dire si la boîte est
+     * réellement surveillée.
+     */
+    waitForMessage(timeoutSeconds: number, folder?: string, options?: {
+        watcher?: boolean;
+    }): Promise<WaitResult>;
     private request;
 }

package/dist/src/client/messenger-client.js

@@ -139,10 +139,15 @@ export class MessengerClient {
         const { moved } = await this.request("DELETE", `/api/folders/${encodeURIComponent(name)}`);
         return moved;
     }
-    async waitForMessage(timeoutSeconds, folder) {
+    /**
+     * `watcher` signale une attente tenue par un veilleur `--watch`, et non par un
+     * `wait_for_message` ponctuel : c'est ce qui permet au serveur de dire si la boîte est
+     * réellement surveillée.
+     */
+    async waitForMessage(timeoutSeconds, folder, options = {}) {
         // L'attente longue peut dépasser le délai HTTP par défaut : on l'étend d'une marge.
         return this.request("GET", "/api/wait", {
-            query: { timeout_seconds: timeoutSeconds, folder },
+            query: { timeout_seconds: timeoutSeconds, folder, watcher: options.watcher ? "true" : undefined },
             timeoutMs: timeoutSeconds * 1000 + this.config.timeoutMs,
         });
     }

package/dist/src/core/types.d.ts

@@ -67,8 +67,23 @@ export interface ListMessagesOptions {
     limit?: number;
     offset?: number;
 }
+/**
+ * Présence d'un veilleur (`--watch`) sur une boîte, telle que la voit le serveur.
+ *
+ * `armed: false` veut dire que personne n'écoute : les messages arriveront en boîte,
+ * mais aucun agent n'en sera averti tant qu'il ne regarde pas de lui-même.
+ */
+export interface WatcherStatus {
+    armed: boolean;
+    /** Depuis quand ce veilleur est en place, ou null s'il n'y en a pas. */
+    since: string | null;
+    /** Dernière attente observée, y compris pour un veilleur qui vient de disparaître. */
+    last_seen: string | null;
+}
 export interface MailboxStats {
     agent_id: string;
     unread_total: number;
     folders: FolderInfo[];
+    /** Absent des réponses du store : ajouté par le serveur, qui seul voit les connexions. */
+    watcher?: WatcherStatus;
 }

package/dist/src/mcp/tools.js

@@ -240,7 +240,12 @@ export async function callTool(client, name, rawArgs) {
             if (client.isAttachedElsewhere) {
                 lines.push(`Attached to another mailbox. This session's own mailbox is ${client.sessionAgentId}.`);
             }
-            lines.push(`Mailbox server: ${client.serverUrl}${health ? ` (v${health.version}, ${health.agents} mailbox(es))` : " (unreachable health endpoint)"}`, `Unread (excluding trash): ${stats.unread_total}`, "Folders:", ...folders);
+            lines.push(`Mailbox server: ${client.serverUrl}${health ? ` (v${health.version}, ${health.agents} mailbox(es))` : " (unreachable health endpoint)"}`, 
+            // Sans veilleur, un message arrive en boîte sans que personne n'en soit averti.
+            // Le dire ici est le seul moyen pour l'agent de s'en apercevoir.
+            stats.watcher?.armed
+                ? `Notifications: armed — incoming messages will interrupt you (watcher since ${stats.watcher.since}).`
+                : "Notifications: NOT armed — no incoming message will reach you. Call enable_notifications.", `Unread (excluding trash): ${stats.unread_total}`, "Folders:", ...folders);
             return lines.join("\n");
         }
         case "attach_to_mailbox": {
@@ -371,6 +376,15 @@ export async function callTool(client, name, rawArgs) {
             writeHandoff({ mailbox, serverUrl: client.serverUrl, token: client.tokenForHandoff });
             const stats = await client.stats().catch(() => null);
             const pending = stats?.folders.find((f) => f.name === "inbox")?.unread ?? 0;
+            // Un veilleur déjà en place suffit : en armer un second doublerait chaque
+            // notification sans rien apporter.
+            if (stats?.watcher?.armed) {
+                return [
+                    `Notifications are already live on mailbox \`${mailbox}\` (watcher armed since ${stats.watcher.since}).`,
+                    "Nothing to do: keep working, incoming messages will interrupt you on their own.",
+                    "Do not arm a second watcher — you would get every message twice.",
+                ].join("\n");
+            }
             const lines = [
                 `Notifications enabled for mailbox \`${mailbox}\`.`,
                 "",

package/dist/src/server/app.js

@@ -8,6 +8,7 @@ import { rateLimit } from "express-rate-limit";
 import { z } from "zod";
 import { MessengerError, normalizeAgentId } from "../core/store.js";
 import { PRIORITIES } from "../core/types.js";
+import { WatcherRegistry } from "./watchers.js";
 import { APP_VERSION } from "../version.js";
 import { logger } from "../logger.js";
 const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "ui");
@@ -51,6 +52,9 @@ const folderSchema = z.object({ name: z.string().trim().min(1).max(40) });
 const waitQuerySchema = z.object({
     timeout_seconds: z.coerce.number().int().min(1).optional(),
     folder: z.string().trim().min(1).optional(),
+    // Distingue le veilleur d'un `wait_for_message` ordinaire : les deux tiennent la même
+    // attente longue, mais seul le premier prouve que l'agent est joignable en continu.
+    watcher: z.enum(["true", "1"]).optional(),
 });
 const adminListSchema = z.object({
     search: z.string().trim().min(1).optional(),
@@ -61,6 +65,8 @@ const adminListSchema = z.object({
 });
 export function createApp({ store, config }) {
     const app = express();
+    // Présence des veilleurs : état de connexion, donc en mémoire du processus.
+    const watchers = new WatcherRegistry();
     app.disable("x-powered-by");
     app.set("trust proxy", false);
     app.use(helmet({
@@ -136,7 +142,7 @@ export function createApp({ store, config }) {
         res.json({ agent });
     });
     api.get("/mailbox", (req, res) => {
-        res.json(store.stats(req.agentId));
+        res.json({ ...store.stats(req.agentId), watcher: watchers.status(req.agentId) });
     });
     api.post("/messages", (req, res) => {
         const input = sendSchema.parse(req.body ?? {});
@@ -190,16 +196,20 @@ export function createApp({ store, config }) {
     // l'appelant ; les non-lus déjà présents sont ignorés (sinon l'outil rendrait la main
     // immédiatement tant que la boîte n'est pas vidée).
     api.get("/wait", (req, res) => {
-        const { timeout_seconds, folder } = waitQuerySchema.parse(req.query);
+        const { timeout_seconds, folder, watcher } = waitQuerySchema.parse(req.query);
         const agentId = req.agentId;
         const timeoutSeconds = Math.min(timeout_seconds ?? 30, config.maxWaitSeconds);
         if (folder && !store.listFolders(agentId).some((f) => f.name === folder)) {
             throw new MessengerError(`unknown folder: ${folder}`, 404);
         }
+        // Le relâchement doit couvrir les trois sorties possibles : message, expiration,
+        // client parti. Un compteur qui ne redescend pas ferait croire à un veilleur éternel.
+        const releaseWatcher = watcher ? watchers.begin(agentId) : () => { };
         const done = (payload) => {
             clearTimeout(timer);
             store.off("message", onMessage);
             req.off("close", onClose);
+            releaseWatcher();
             if (!res.headersSent)
                 res.json(payload);
         };
@@ -215,6 +225,7 @@ export function createApp({ store, config }) {
         const onClose = () => {
             clearTimeout(timer);
             store.off("message", onMessage);
+            releaseWatcher();
         };
         const timer = setTimeout(() => done({ timed_out: true, message: null }), timeoutSeconds * 1000);
         store.on("message", onMessage);

package/dist/src/server/watchers.d.ts

@@ -0,0 +1,10 @@
+import type { WatcherStatus } from "../core/types.js";
+export declare class WatcherRegistry {
+    private readonly now;
+    private readonly presence;
+    /** L'horloge est injectable : le délai de grâce se teste sans faire attendre la suite. */
+    constructor(now?: () => number);
+    /** Déclare une attente de veilleur. La fonction rendue la clôt, et doit toujours être appelée. */
+    begin(agentId: string): () => void;
+    status(agentId: string): WatcherStatus;
+}

package/dist/src/server/watchers.js

@@ -0,0 +1,69 @@
+/**
+ * Présence des veilleurs, par boîte.
+ *
+ * L'armement du veilleur dépend de l'agent : rien ne peut le déclencher à sa place, et
+ * un agent qui saute l'étape se croit joignable sans l'être. Ce registre rend le fait
+ * observable — `whoami` peut alors répondre « armé » ou « pas armé » plutôt que rien.
+ *
+ * État de connexion, donc volatile : il vit en mémoire du processus serveur et disparaît
+ * avec lui. Le mettre en base ferait croire à un veilleur qui n'existe plus.
+ */
+/**
+ * Un veilleur enchaîne des attentes longues ; entre deux, il n'est plus connecté pendant
+ * quelques millisecondes. Ce délai de grâce évite de le déclarer absent dans cet
+ * intervalle, ou juste après qu'un message a mis fin à son attente.
+ */
+const GRACE_MS = 2 * 60 * 1000;
+export class WatcherRegistry {
+    now;
+    presence = new Map();
+    /** L'horloge est injectable : le délai de grâce se teste sans faire attendre la suite. */
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Déclare une attente de veilleur. La fonction rendue la clôt, et doit toujours être appelée. */
+    begin(agentId) {
+        const now = this.now();
+        const current = this.presence.get(agentId);
+        // Une absence dépassant le délai de grâce commence une nouvelle série : `since`
+        // désigne le moment où ce veilleur-ci s'est armé, pas un ancêtre oublié.
+        const continuing = current && now - current.lastSeen <= GRACE_MS;
+        const entry = continuing
+            ? { ...current, inflight: current.inflight + 1, lastSeen: now }
+            : { inflight: 1, since: now, lastSeen: now };
+        this.presence.set(agentId, entry);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const active = this.presence.get(agentId);
+            if (!active)
+                return;
+            // On garde l'entrée après la dernière attente : c'est elle qui porte le délai de
+            // grâce, le temps que le veilleur relance son tour suivant.
+            this.presence.set(agentId, {
+                ...active,
+                inflight: Math.max(0, active.inflight - 1),
+                lastSeen: this.now(),
+            });
+        };
+    }
+    status(agentId) {
+        const now = this.now();
+        const entry = this.presence.get(agentId);
+        if (!entry)
+            return { armed: false, since: null, last_seen: null };
+        const armed = entry.inflight > 0 || now - entry.lastSeen <= GRACE_MS;
+        if (!armed) {
+            // Purge à la lecture : sans veilleur pour cette boîte, l'entrée n'a plus d'objet.
+            this.presence.delete(agentId);
+            return { armed: false, since: null, last_seen: new Date(entry.lastSeen).toISOString() };
+        }
+        return {
+            armed: true,
+            since: new Date(entry.since).toISOString(),
+            last_seen: new Date(entry.lastSeen).toISOString(),
+        };
+    }
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.3";
+export declare const APP_VERSION = "1.0.4";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Généré par scripts/generate-version.js — ne pas modifier à la main.
-export const APP_VERSION = "1.0.3";
+export const APP_VERSION = "1.0.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-messenger",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "npm run build && vitest run",