@imenam/mcp-messenger 1.0.6 → 1.0.8

package/.env.example

@@ -13,7 +13,8 @@ MESSENGER_PORT=3600
 # Chemin du fichier SQLite (défaut : <cwd>/data/messenger.db).
 # MESSENGER_DB_PATH=/var/lib/mcp-messenger/messenger.db
 
-# Jeton exigé sur TOUTE requête entrante (API, /health, console web).
+# Jeton exigé sur TOUTE requête de données (API, /health, données de la console).
+# Seule la page de la console (/ui), qui ne contient aucun secret, est servie sans lui.
 # OBLIGATOIRE : sans MESSENGER_TOKEN ni MESSENGER_AGENT_TOKENS, le serveur refuse
 # de démarrer. Générer avec : npx @imenam/mcp-messenger --generate-token
 MESSENGER_TOKEN=change-me
@@ -23,8 +24,10 @@ MESSENGER_TOKEN=change-me
 # Format : agent_id:token,agent_id:token
 # MESSENGER_AGENT_TOKENS=planner:tok-planner,coder:tok-coder
 
-# Jeton de la console web. À défaut, MESSENGER_TOKEN fait office ; il devient
-# obligatoire si seul MESSENGER_AGENT_TOKENS est utilisé.
+# Jeton de la console web, saisi une fois dans son formulaire (/ui) : le serveur ouvre
+# alors une session de 12 h dans un cookie HttpOnly, sans jamais y mettre le jeton.
+# À défaut, MESSENGER_TOKEN fait office ; il devient obligatoire si seul
+# MESSENGER_AGENT_TOKENS est utilisé.
 # MESSENGER_ADMIN_TOKEN=change-me-too
 
 # Rate limiting (par IP).

package/README.md

@@ -97,7 +97,7 @@ la session MCP démarre quand même et l'enregistrement se fera au premier appel
 
 L'agent A appelle `send_message` avec `to: ["coder"]`, l'agent B voit le message via
 `list_messages` puis `read_message`, et répond avec `reply_to` pour rester dans le fil.
-Le fil se nomme au passage (`thread_title` sur `send_message`, ou `set_label` plus tard).
+Le fil se nomme au passage (`thread_name` sur `send_message`, ou `rename_thread` plus tard).
 `wait_for_message` permet d'attendre une réponse sans faire tourner une boucle d'appels : il ne
 rend la main que sur un message arrivé *après* le début de l'attente, les non-lus déjà en boîte
 ne l'interrompent pas.
@@ -177,10 +177,11 @@ superviseur capable de lire les lignes d'un processus peut la brancher. Sans rel
 |---|---|
 | `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_label` | Nommer sa boîte, ou un fil (`thread_id`), en langue naturelle |
+| `rename_mailbox` | Nommer ou renommer sa boîte (de quoi la session s'occupe) ; le nom de l'agent, posé par la configuration, reste |
+| `rename_thread` | Nommer ou renommer un fil (`thread_id`) ; le nom est partagé par tous ses participants |
 | `list_threads` | Carte des conversations : nom, participants, non-lus, dernière activité |
-| `list_agents` | Annuaire : qui est joignable, du plus récemment actif au plus ancien |
-| `send_message` | Envoyer à un ou plusieurs agents (`to`, `cc`, `priority`, `reply_to`, `thread_title`) |
+| `list_agents` | Annuaire : qui est joignable, du plus récemment actif au plus ancien ; la boîte de l'appelant n'y figure pas |
+| `send_message` | Écrire à un agent — un seul destinataire par message (`to`, `priority`, `reply_to`, `thread_name`) |
 | `list_messages` | Lister la boîte (filtres : dossier, non lus, expéditeur, fil, texte libre) |
 | `read_message` | Lire un message en entier ; le marque lu par défaut |
 | `get_thread` | Relire toute une conversation, du plus ancien au plus récent |
@@ -194,12 +195,18 @@ superviseur capable de lire les lignes d'un processus peut la brancher. Sans rel
 
 **Noms lisibles** — voir « Nommer les boîtes et les fils » ci-dessous.
 
+**Un message, deux boîtes** — un échange lie exactement deux agents *distincts* : `to` prend
+une seule adresse, il n'y a ni diffusion ni copie, et une boîte ne peut pas s'écrire à
+elle-même. Pour toucher plusieurs agents, on leur envoie un message chacun, dans son propre
+fil. C'est aussi pourquoi `list_agents` ne montre jamais l'appelant : la seule adresse qu'il
+ne peut pas viser n'a pas à figurer dans son annuaire.
+
 **Dossiers système** — toujours présents, non supprimables : `inbox`, `sent`, `archive`,
 `trash`. Les dossiers personnalisés sont propres à chaque boîte.
 
 **Ce que voit un agent** : uniquement les livraisons de la boîte à laquelle il est attaché. Un message adressé à `coder`
 est invisible pour tout autre agent, y compris via son identifiant. Supprimer un message ne
-touche que sa propre copie : les autres destinataires gardent la leur.
+touche que sa propre copie : l'autre partie garde la sienne.
 
 ---
 
@@ -221,25 +228,58 @@ ont deux boîtes distinctes et ne se volent pas leur courrier.
 2. Transmets-la à l'agent B, qui l'utilise dans `send_message`.
 
 Comme les adresses sont opaques, demande aux agents de nommer leur boîte
-(`set_label`) : le libellé apparaît dans `list_agents` et dans la console web, ce
+(`rename_mailbox`) : le nom apparaît dans `list_agents` et dans la console web, ce
 qui permet de retrouver une adresse perdue.
 
+### Deux noms par boîte : l'agent et la boîte
+
+Une boîte porte deux identités, qui répondent à deux questions différentes et ne changent
+pas au même rythme :
+
+| | D'où vient-il ? | De quoi s'occupe-t-il ? |
+|---|---|---|
+| Champ | `agent_name`, `agent_description` | `display_name`, `description` |
+| Posé par | la configuration (`MESSENGER_AGENT_NAME`, `MESSENGER_AGENT_DESCRIPTION`) | l'agent lui-même, via `rename_mailbox` |
+| Change | jamais depuis une session | librement, au fil du travail |
+| Exemple | `Ai Corrector Dev` | `Correction du parseur de copies` |
+
+Le nom de l'agent seul ne distingue pas deux sessions ouvertes sur le même projet ; le nom
+de la boîte seul ne dit pas d'où l'agent écrit. L'annuaire (`list_agents`), `whoami` et la
+console web montrent donc toujours les deux, sous la forme `Agent · Boîte`. Renommer la
+boîte ne touche jamais au nom de l'agent.
+
+**Un nom d'agent ne désigne personne.** C'est le piège de ce modèle : plusieurs boîtes
+portent le même `agent_name`, une par session lancée depuis la même configuration. Un agent
+qui croise son propre nom d'agent dans l'annuaire regarde une *autre* session du même
+projet, jamais la sienne — sa boîte, elle, n'y figure pas du tout. Seule l'adresse identifie
+une session. Ce rappel est servi à trois endroits, du plus tôt au plus tard : les
+instructions du serveur MCP (reçues à la connexion, avant le premier outil), la ligne qui
+suit `Agent:` dans `whoami`, et le pied de l'annuaire dans `list_agents`.
+
+**Les adresses ne se recopient pas à la main.** Le serveur attache l'expéditeur et le
+destinataire à chaque message, et le lecteur les voit dans l'en-tête. Écrire son adresse
+dans le corps n'ajoute rien et se met à mentir dès qu'elle est erronée ou périmée —
+`send_message` le dit dans sa description et dans celle de `body`.
+
 ### Nommer les boîtes et les fils
 
 Les identifiants (`box_…`, `thr_…`) ne disent rien de ce qui se passe. Deux noms en langue
-naturelle viennent par-dessus, et un seul outil les pose :
+naturelle viennent par-dessus, un outil pour chacun :
 
 ```
-set_label(label: "Développement des tests unitaires du parser")
-    → nomme la boîte de la session
+rename_mailbox(name: "Développement des tests unitaires du parser")
+    → nomme la boîte de la session (le nom de l'agent reste)
 
-set_label(thread_id: "thr_…", label: "Le test échoue sur un bug applicatif")
+rename_thread(thread_id: "thr_…", name: "Le test échoue sur un bug applicatif")
     → nomme le fil
 ```
 
-Le plus simple reste de nommer un fil au moment où on l'ouvre, via `thread_title` sur
+Le plus simple reste de nommer un fil au moment où on l'ouvre, via `thread_name` sur
 `send_message` : l'agent qui écrit le premier message sait déjà de quoi il parle.
 
+L'ancien outil `set_label`, qui cumulait les deux rôles, reste accepté sans être publié :
+une session lancée avant la mise à jour peut encore l'appeler.
+
 Un fil n'a **qu'un seul nom, partagé par tous ses participants** — ils discutent du même
 sujet, ils doivent lire le même intitulé. N'importe quel participant peut le renommer, et
 le dernier a le dernier mot ; le serveur retient qui (`named_by`). Un agent extérieur au
@@ -325,7 +365,7 @@ Toutes les variables sont documentées dans [`.env.example`](.env.example). L'es
 | `MESSENGER_AGENT_ID` | — | Adresse **fixe**. Vide (recommandé) = une boîte par session |
 | `MESSENGER_SERVER_URL` | ✅ | `http://` ou `https://`, local ou distant |
 | `MESSENGER_TOKEN` | ✅ | Jeton présenté au serveur, sur chaque appel |
-| `MESSENGER_AGENT_NAME` | — | Nom affiché dans l'annuaire |
+| `MESSENGER_AGENT_NAME` | — | Nom de l'agent (le projet, typiquement), affiché à côté du nom de la boîte |
 | `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour ses correspondants |
 | `MESSENGER_TIMEOUT_MS` | `15000` | Délai maximal d'un appel HTTP |
 | `MESSENGER_STATE_DIR` | — | Répertoire des relais vers le veilleur (défaut : `~/.mcp-messenger`) |
@@ -344,7 +384,7 @@ la console (cookie), qui elle n'ouvre rien d'autre.
 |---|---|---|
 | `GET` | `/health` | État du service |
 | `POST` | `/api/agents/register` | S'inscrire à l'annuaire (`fresh: true` = exige une adresse neuve) |
-| `GET` | `/api/agents` | Annuaire des boîtes |
+| `GET` | `/api/agents` | Annuaire des boîtes, sauf celle de l'appelant |
 | `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, et présence d'un veilleur (`watcher`) |

package/dist/src/cli/setup-mcp.js

@@ -44,7 +44,7 @@ const REQUIRED_VARS = [
 ];
 const OPTIONAL_VARS = [
     ["MESSENGER_AGENT_ID", "adresse fixe : à laisser vide pour une boîte par session"],
-    ["MESSENGER_AGENT_NAME", "nom affiché dans l'annuaire des agents"],
+    ["MESSENGER_AGENT_NAME", "nom de l'agent (le projet, typiquement) ; distinct du nom de la boîte, que l'agent pose lui-même"],
     ["MESSENGER_AGENT_DESCRIPTION", "à quoi sert cet agent, pour ses correspondants"],
     ["MESSENGER_TIMEOUT_MS", "délai maximal d'un appel HTTP (défaut : 15000)"],
 ];

package/dist/src/cli/watch.js

@@ -44,8 +44,8 @@ export function resolveWatchConfig(mailbox, env = process.env) {
             agentId: target,
             serverUrl: serverUrl.replace(/\/+$/, ""),
             token: handoff?.token ?? env.MESSENGER_TOKEN?.trim() ?? null,
-            displayName: null,
-            description: null,
+            agentName: null,
+            agentDescription: null,
             timeoutMs: Number(env.MESSENGER_TIMEOUT_MS) || 15_000,
         },
     };

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

@@ -52,7 +52,7 @@ export declare class MessengerClient {
     register(options?: {
         fresh?: boolean;
     }): Promise<Agent>;
-    /** Renomme la boîte courante, pour la rendre reconnaissable dans l'annuaire. */
+    /** Renomme la boîte courante (pas l'agent), pour dire de quoi cette session s'occupe. */
     updateProfile(profile: {
         display_name?: string | null;
         description?: string | null;
@@ -61,8 +61,7 @@ export declare class MessengerClient {
     listAgents(): Promise<AgentDirectoryEntry[]>;
     stats(): Promise<MailboxStats>;
     sendMessage(input: {
-        to: string[];
-        cc?: string[];
+        to: string;
         subject: string;
         body: string;
         priority?: Priority;

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

@@ -68,14 +68,14 @@ export class MessengerClient {
     async register(options = {}) {
         const { agent } = await this.request("POST", "/api/agents/register", {
             body: {
-                display_name: this.config.displayName,
-                description: this.config.description,
+                agent_name: this.config.agentName,
+                agent_description: this.config.agentDescription,
                 fresh: options.fresh ?? false,
             },
         });
         return agent;
     }
-    /** Renomme la boîte courante, pour la rendre reconnaissable dans l'annuaire. */
+    /** Renomme la boîte courante (pas l'agent), pour dire de quoi cette session s'occupe. */
     async updateProfile(profile) {
         const { agent } = await this.request("PATCH", "/api/agents/me", { body: profile });
         return agent;

package/dist/src/config.d.ts

@@ -27,8 +27,9 @@ export interface AgentConfig {
     agentId: string | null;
     serverUrl: string;
     token: string | null;
-    displayName: string | null;
-    description: string | null;
+    /** Identité de l'agent, stable : d'où il écrit (le projet). Distincte du nom de la boîte. */
+    agentName: string | null;
+    agentDescription: string | null;
     timeoutMs: number;
 }
 export declare function isLoopbackHost(host: string): boolean;

package/dist/src/config.js

@@ -74,8 +74,8 @@ export function loadAgentConfig(env = process.env) {
         agentId,
         serverUrl: rawUrl.replace(/\/+$/, ""),
         token: nonEmpty(env.MESSENGER_TOKEN),
-        displayName: nonEmpty(env.MESSENGER_AGENT_NAME),
-        description: nonEmpty(env.MESSENGER_AGENT_DESCRIPTION),
+        agentName: nonEmpty(env.MESSENGER_AGENT_NAME),
+        agentDescription: nonEmpty(env.MESSENGER_AGENT_DESCRIPTION),
         timeoutMs: parseIntEnv(env.MESSENGER_TIMEOUT_MS, 15_000, "MESSENGER_TIMEOUT_MS"),
     };
 }

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

@@ -5,6 +5,15 @@ export declare class MessengerError extends Error {
     readonly status: number;
     constructor(message: string, status?: number);
 }
+export interface EnsureAgentOptions {
+    registered?: boolean;
+    /** Identité de l'agent : d'où il vient. Posée par la configuration. */
+    agent_name?: string | null;
+    agent_description?: string | null;
+    /** Nom de la boîte : de quoi cette session s'occupe. Posé par l'agent lui-même. */
+    display_name?: string | null;
+    description?: string | null;
+}
 export interface StoreEvents {
     /** Émis pour chaque destinataire d'un message, y compris la copie « sent » de l'expéditeur. */
     message: [{
@@ -26,16 +35,21 @@ export declare class MessageStore extends EventEmitter<StoreEvents> {
     constructor(dbPath: string);
     private migrate;
     close(): void;
-    /** Crée la fiche au besoin. `registered: false` = agent connu seulement comme destinataire. */
-    ensureAgent(id: string, opts?: {
-        registered?: boolean;
-        display_name?: string | null;
-        description?: string | null;
-    }): Agent;
+    /**
+     * Crée la fiche au besoin. `registered: false` = agent connu seulement comme destinataire.
+     * Chaque champ omis (ou null) laisse la valeur en place : l'enregistrement pose l'identité
+     * de l'agent sans toucher au nom de la boîte, et `rename_mailbox` fait l'inverse.
+     */
+    ensureAgent(id: string, opts?: EnsureAgentOptions): Agent;
     touchAgent(id: string): void;
     getAgent(id: string): Agent | null;
-    /** Annuaire classé par activité décroissante : ce qui bouge est en tête, l'id ne trie rien. */
-    listAgents(): AgentDirectoryEntry[];
+    /**
+     * Annuaire classé par activité décroissante : ce qui bouge est en tête, l'id ne trie rien.
+     *
+     * `exclude` retire une adresse du résultat : l'annuaire servi à un agent ne lui montre pas
+     * sa propre boîte, la seule à laquelle il ne peut pas écrire.
+     */
+    listAgents(exclude?: string): AgentDirectoryEntry[];
     sendMessage(input: SendMessageInput): SendMessageResult;
     listMessages(agentId: string, opts?: ListMessagesOptions): MessageSummary[];
     getMessage(agentId: string, messageId: string, markRead?: boolean): Message;
@@ -103,6 +117,7 @@ export declare class MessageStore extends EventEmitter<StoreEvents> {
     /** Filtre les ids fournis sur ceux réellement livrés à cet agent (isolation des boîtes). */
     private ownedMessageIds;
     private assertFolderExists;
+    /** Destinataire de chaque message demandé, par identifiant de message. */
     private recipientsFor;
     private toSummary;
     private toMessage;

package/dist/src/core/store.js

@@ -52,9 +52,11 @@ export class MessageStore extends EventEmitter {
     migrate() {
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS agents (
-        id           TEXT PRIMARY KEY,
-        display_name TEXT,
-        description  TEXT,
+        id                TEXT PRIMARY KEY,
+        agent_name        TEXT,
+        agent_description TEXT,
+        display_name      TEXT,
+        description       TEXT,
         created_at   TEXT NOT NULL,
         last_seen_at TEXT,
         registered   INTEGER NOT NULL DEFAULT 0
@@ -103,6 +105,21 @@ export class MessageStore extends EventEmitter {
       CREATE INDEX IF NOT EXISTS idx_deliveries_message ON deliveries (message_id);
       CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages (thread_id, created_at);
     `);
+        // Bases antérieures à la séparation agent / boîte : `display_name` y tenait les deux
+        // rôles, et venait presque toujours de la configuration (le nom du projet). On le
+        // déplace vers l'identité de l'agent ; la boîte repart sans nom, à poser par l'agent.
+        const agentColumns = this.db.prepare("PRAGMA table_info(agents)").all().map((c) => c.name);
+        if (!agentColumns.includes("agent_name")) {
+            this.db.exec(`
+        ALTER TABLE agents ADD COLUMN agent_name TEXT;
+        ALTER TABLE agents ADD COLUMN agent_description TEXT;
+        UPDATE agents
+           SET agent_name = display_name,
+               agent_description = description,
+               display_name = NULL,
+               description = NULL;
+      `);
+        }
         // Bases antérieures aux fils nommés : chaque fil déjà présent reçoit sa ligne, sans
         // titre. L'affichage retombe alors sur le sujet d'ouverture, comme avant.
         this.db.exec(`
@@ -117,25 +134,31 @@ export class MessageStore extends EventEmitter {
         this.db.close();
     }
     // --- Agents -------------------------------------------------------------
-    /** Crée la fiche au besoin. `registered: false` = agent connu seulement comme destinataire. */
+    /**
+     * Crée la fiche au besoin. `registered: false` = agent connu seulement comme destinataire.
+     * Chaque champ omis (ou null) laisse la valeur en place : l'enregistrement pose l'identité
+     * de l'agent sans toucher au nom de la boîte, et `rename_mailbox` fait l'inverse.
+     */
     ensureAgent(id, opts = {}) {
         const now = new Date().toISOString();
         const existing = this.db.prepare("SELECT id FROM agents WHERE id = ?").get(id);
         if (!existing) {
             this.db
-                .prepare(`INSERT INTO agents (id, display_name, description, created_at, last_seen_at, registered)
-           VALUES (?, ?, ?, ?, ?, ?)`)
-                .run(id, opts.display_name ?? null, opts.description ?? null, now, opts.registered ? now : null, opts.registered ? 1 : 0);
+                .prepare(`INSERT INTO agents (id, agent_name, agent_description, display_name, description, created_at, last_seen_at, registered)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, opts.agent_name ?? null, opts.agent_description ?? null, opts.display_name ?? null, opts.description ?? null, now, opts.registered ? now : null, opts.registered ? 1 : 0);
         }
         else {
             this.db
                 .prepare(`UPDATE agents
-              SET display_name = COALESCE(?, display_name),
-                  description  = COALESCE(?, description),
-                  registered   = MAX(registered, ?),
-                  last_seen_at = CASE WHEN ? = 1 THEN ? ELSE last_seen_at END
+              SET agent_name        = COALESCE(?, agent_name),
+                  agent_description = COALESCE(?, agent_description),
+                  display_name      = COALESCE(?, display_name),
+                  description       = COALESCE(?, description),
+                  registered        = MAX(registered, ?),
+                  last_seen_at      = CASE WHEN ? = 1 THEN ? ELSE last_seen_at END
             WHERE id = ?`)
-                .run(opts.display_name ?? null, opts.description ?? null, opts.registered ? 1 : 0, opts.registered ? 1 : 0, now, id);
+                .run(opts.agent_name ?? null, opts.agent_description ?? null, opts.display_name ?? null, opts.description ?? null, opts.registered ? 1 : 0, opts.registered ? 1 : 0, now, id);
         }
         return this.getAgent(id);
     }
@@ -146,13 +169,20 @@ export class MessageStore extends EventEmitter {
         const row = this.db.prepare("SELECT * FROM agents WHERE id = ?").get(id);
         return row ? { ...row, registered: Boolean(row.registered) } : null;
     }
-    /** Annuaire classé par activité décroissante : ce qui bouge est en tête, l'id ne trie rien. */
-    listAgents() {
+    /**
+     * Annuaire classé par activité décroissante : ce qui bouge est en tête, l'id ne trie rien.
+     *
+     * `exclude` retire une adresse du résultat : l'annuaire servi à un agent ne lui montre pas
+     * sa propre boîte, la seule à laquelle il ne peut pas écrire.
+     */
+    listAgents(exclude) {
+        const excluded = exclude ? normalizeAgentId(exclude) : "";
         const rows = this.db
             .prepare(`SELECT a.*, ${LAST_ACTIVITY} AS last_activity_at
            FROM agents a
+          WHERE a.id != ?
           ORDER BY last_activity_at DESC, a.id`)
-            .all();
+            .all(excluded);
         return rows.map((r) => ({
             ...r,
             registered: Boolean(r.registered),
@@ -169,11 +199,14 @@ export class MessageStore extends EventEmitter {
         const from = normalizeAgentId(input.from);
         if (!from)
             throw new MessengerError("sender agent id is required");
-        const to = dedupe(input.to.map(normalizeAgentId).filter(Boolean));
-        // Un même agent ne peut pas être à la fois destinataire principal et en copie.
-        const cc = dedupe((input.cc ?? []).map(normalizeAgentId).filter(Boolean)).filter((id) => !to.includes(id));
-        if (to.length === 0)
-            throw new MessengerError("at least one recipient is required in `to`");
+        // Un message va d'une boîte à une seule autre : pas de diffusion, pas de copie.
+        const to = normalizeAgentId(input.to);
+        if (!to)
+            throw new MessengerError("a recipient is required in `to`");
+        // Une boîte ne se parle pas à elle-même : la copie « sent » et la copie « inbox »
+        // désigneraient le même agent, et le fil n'aurait qu'un seul participant.
+        if (to === from)
+            throw new MessengerError("an agent cannot send a message to itself");
         const title = normalizeLabel(input.thread_title, THREAD_TITLE_MAX, "thread_title");
         const threadDescription = normalizeLabel(input.thread_description, THREAD_DESCRIPTION_MAX, "thread_description");
         let threadId;
@@ -191,18 +224,16 @@ export class MessageStore extends EventEmitter {
         const messageId = newId("msg");
         const now = new Date().toISOString();
         const priority = input.priority ?? "normal";
-        const unknownRecipients = [...to, ...cc].filter((id) => !this.getAgent(id)?.registered);
+        const unknownRecipient = !this.getAgent(to)?.registered;
         const deliveries = [
-            ...to.map((agent_id) => ({ agent_id, role: "to", folder: "inbox", read_at: null })),
-            ...cc.map((agent_id) => ({ agent_id, role: "cc", folder: "inbox", read_at: null })),
+            { agent_id: to, role: "to", folder: "inbox", read_at: null },
             { agent_id: from, role: "sender", folder: "sent", read_at: now },
         ];
         this.db.transaction(() => {
             this.ensureAgent(from);
             // Écrire est le signe d'activité le plus fiable : l'annuaire s'appuie dessus.
             this.touchAgent(from);
-            for (const id of [...to, ...cc])
-                this.ensureAgent(id);
+            this.ensureAgent(to);
             // Le fil naît avec son premier message ; sur une réponse, la ligne existe déjà et
             // n'est touchée que si l'expéditeur fournit un nouveau titre.
             this.db
@@ -231,8 +262,8 @@ export class MessageStore extends EventEmitter {
             thread_id: threadId,
             thread_title: this.getThreadInfo(threadId)?.title ?? null,
             created_at: now,
-            delivered_to: [...to, ...cc],
-            unknown_recipients: unknownRecipients,
+            delivered_to: to,
+            unknown_recipient: unknownRecipient,
         };
     }
     // --- Lecture ------------------------------------------------------------
@@ -282,7 +313,7 @@ export class MessageStore extends EventEmitter {
            JOIN messages m ON m.id = d.message_id
            ${THREAD_JOIN}
           WHERE d.agent_id = ? AND d.message_id = ?
-          ORDER BY CASE d.role WHEN 'to' THEN 0 WHEN 'cc' THEN 1 ELSE 2 END
+          ORDER BY CASE d.role WHEN 'to' THEN 0 ELSE 1 END
           LIMIT 1`)
             .get(agentId, messageId);
         if (!row)
@@ -628,6 +659,7 @@ export class MessageStore extends EventEmitter {
         if (!row)
             throw new MessengerError(`unknown folder: ${folder}`, 404);
     }
+    /** Destinataire de chaque message demandé, par identifiant de message. */
     recipientsFor(messageIds) {
         const map = new Map();
         const ids = dedupe(messageIds);
@@ -635,29 +667,20 @@ export class MessageStore extends EventEmitter {
             return map;
         const placeholders = ids.map(() => "?").join(",");
         const rows = this.db
-            .prepare(`SELECT message_id, agent_id, role FROM deliveries
-          WHERE message_id IN (${placeholders}) AND role != 'sender'
-          ORDER BY agent_id`)
+            .prepare(`SELECT message_id, agent_id FROM deliveries
+          WHERE message_id IN (${placeholders}) AND role = 'to'`)
             .all(...ids);
-        for (const row of rows) {
-            const entry = map.get(row.message_id) ?? { to: [], cc: [] };
-            if (row.role === "to")
-                entry.to.push(row.agent_id);
-            else if (row.role === "cc")
-                entry.cc.push(row.agent_id);
-            map.set(row.message_id, entry);
-        }
+        for (const row of rows)
+            map.set(row.message_id, row.agent_id);
         return map;
     }
     toSummary(row, recipients) {
-        const rcpt = recipients.get(row.message_id) ?? { to: [], cc: [] };
         return {
             message_id: row.message_id,
             thread_id: row.thread_id,
             thread_title: row.thread_title,
             from: row.sender_id,
-            to: rcpt.to,
-            cc: rcpt.cc,
+            to: recipients.get(row.message_id) ?? "",
             subject: row.subject,
             preview: preview(row.body),
             priority: row.priority,

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

@@ -3,11 +3,22 @@ export declare const SYSTEM_FOLDERS: readonly ["inbox", "sent", "archive", "tras
 export type SystemFolder = (typeof SYSTEM_FOLDERS)[number];
 export declare const PRIORITIES: readonly ["low", "normal", "high"];
 export type Priority = (typeof PRIORITIES)[number];
-/** Rôle d'un agent vis-à-vis d'un message : destinataire, copie, ou expéditeur. */
-export declare const DELIVERY_ROLES: readonly ["to", "cc", "sender"];
+/** Rôle d'un agent vis-à-vis d'un message : destinataire ou expéditeur. */
+export declare const DELIVERY_ROLES: readonly ["to", "sender"];
 export type DeliveryRole = (typeof DELIVERY_ROLES)[number];
+/**
+ * Une boîte porte deux identités qui ne bougent pas au même rythme :
+ * - l'agent (`agent_name`, `agent_description`) : d'où il vient, typiquement le projet.
+ *   Posé par la configuration à l'enregistrement, stable pour toute la vie de la boîte.
+ * - la boîte (`display_name`, `description`) : de quoi cette session s'occupe. Vide au
+ *   départ, posé par l'agent lui-même (`rename_mailbox`), et libre de changer.
+ * Le nom de l'agent seul ne distingue pas deux sessions du même projet ; le nom de la boîte
+ * seul ne dit pas où l'agent travaille. La console et l'annuaire montrent les deux.
+ */
 export interface Agent {
     id: string;
+    agent_name: string | null;
+    agent_description: string | null;
     display_name: string | null;
     description: string | null;
     created_at: string;
@@ -26,8 +37,8 @@ export interface AgentDirectoryEntry extends Agent {
 }
 export interface SendMessageInput {
     from: string;
-    to: string[];
-    cc?: string[];
+    /** Un échange lie exactement deux boîtes : un seul destinataire par message. */
+    to: string;
     subject: string;
     body: string;
     priority?: Priority;
@@ -67,9 +78,9 @@ export interface SendMessageResult {
     /** Titre du fil après envoi, null s'il n'a jamais été nommé. */
     thread_title: string | null;
     created_at: string;
-    delivered_to: string[];
-    /** Destinataires jamais enregistrés sur ce serveur — le message les attend malgré tout. */
-    unknown_recipients: string[];
+    delivered_to: string;
+    /** Destinataire jamais enregistré sur ce serveur — le message l'attend malgré tout. */
+    unknown_recipient: boolean;
 }
 export interface MessageSummary {
     message_id: string;
@@ -77,8 +88,7 @@ export interface MessageSummary {
     /** Titre du fil, null tant que personne ne l'a nommé — le `subject` fait alors office. */
     thread_title: string | null;
     from: string;
-    to: string[];
-    cc: string[];
+    to: string;
     subject: string;
     preview: string;
     priority: Priority;

package/dist/src/core/types.js

@@ -1,5 +1,5 @@
 /** Dossiers présents pour tout agent : ils ne peuvent être ni créés ni supprimés. */
 export const SYSTEM_FOLDERS = ["inbox", "sent", "archive", "trash"];
 export const PRIORITIES = ["low", "normal", "high"];
-/** Rôle d'un agent vis-à-vis d'un message : destinataire, copie, ou expéditeur. */
-export const DELIVERY_ROLES = ["to", "cc", "sender"];
+/** Rôle d'un agent vis-à-vis d'un message : destinataire ou expéditeur. */
+export const DELIVERY_ROLES = ["to", "sender"];

package/dist/src/mcp/start.js

@@ -8,9 +8,29 @@ import { newId } from "../core/ids.js";
 import { logger } from "../logger.js";
 import { APP_VERSION } from "../version.js";
 import { TOOLS, callTool } from "./tools.js";
+/**
+ * Ce que l'hôte reçoit à la poignée de main, avant le moindre appel d'outil.
+ *
+ * Deux confusions coûtent cher et n'apparaissent qu'au moment d'écrire, trop tard : croire
+ * que le nom d'agent désigne une session (il est partagé par toutes celles du projet), et
+ * recopier une adresse dans le corps d'un message (le serveur la pose déjà, la copie ment
+ * dès qu'elle vieillit). Les dire ici, c'est les dire avant l'erreur.
+ */
+const INSTRUCTIONS = `mcp-messenger gives this session a mailbox and lets it exchange messages with other agent sessions.
+
+Who you are, and who the others are — read this before writing to anyone:
+- A session is identified by its mailbox address, and by nothing else. \`whoami\` gives you yours.
+- The agent name (e.g. "Ai Corrector Dev") comes from the configuration and says which project the agent works on. It is NOT unique: every session started from that configuration carries it.
+- So several mailboxes in \`list_agents\` can carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — it is another session of the same project, a different agent, with its own mailbox. Compare addresses, never names.
+- Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
+
+Writing:
+- One message goes to exactly one agent, and never to yourself. To reach several agents, send each one its own message.
+- Never write a mailbox address in the body of a message. The server attaches the sender and the recipient to every message, and the reader sees them: an address copied by hand adds nothing and misleads as soon as it is stale or mistaken.
+- Call \`enable_notifications\` once at the start of the session and arm the watcher it hands you. Until then, no incoming message reaches you.`;
 /** Serveur MCP prêt à être branché sur n'importe quel transport (stdio en production, mémoire en test). */
 export function createMcpServer(client) {
-    const server = new Server({ name: "mcp-messenger", version: APP_VERSION }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "mcp-messenger", version: APP_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;