@imenam/mcp-messenger 1.0.33 → 1.0.35

package/.env.example

@@ -1,18 +1,18 @@
-# ---------------------------------------------------------------------------
-# MCP Messenger — configuration
-# Deux modes, deux jeux de variables. Une même installation peut servir aux deux.
-# ---------------------------------------------------------------------------
-
-# === Mode serveur (boîte aux lettres) : `mcp-messenger --server` ===========
-
-# Port d'écoute. L'interface, elle, n'est pas configurable : le serveur écoute
-# toujours sur 127.0.0.1 et refuse de démarrer si MESSENGER_HOST vaut autre chose.
-# Pour l'atteindre depuis une autre machine, placer un reverse proxy devant.
-MESSENGER_PORT=3600
-
-# Chemin du fichier SQLite (défaut : <cwd>/data/messenger.db).
-# MESSENGER_DB_PATH=/var/lib/mcp-messenger/messenger.db
-
+# ---------------------------------------------------------------------------
+# MCP Messenger — configuration
+# Deux modes, deux jeux de variables. Une même installation peut servir aux deux.
+# ---------------------------------------------------------------------------
+
+# === Mode serveur (boîte aux lettres) : `mcp-messenger --server` ===========
+
+# Port d'écoute. L'interface, elle, n'est pas configurable : le serveur écoute
+# toujours sur 127.0.0.1 et refuse de démarrer si MESSENGER_HOST vaut autre chose.
+# Pour l'atteindre depuis une autre machine, placer un reverse proxy devant.
+MESSENGER_PORT=3600
+
+# Chemin du fichier SQLite (défaut : <cwd>/data/messenger.db).
+# MESSENGER_DB_PATH=/var/lib/mcp-messenger/messenger.db
+
 # Aucun secret à poser ici : au premier démarrage, le serveur écrit un code d'installation
 # dans son journal ; la console (/ui) le demande pour créer le compte administrateur
 # (nom d'utilisateur + mot de passe). Les clés des agents se créent ensuite dans la
@@ -20,49 +20,50 @@ MESSENGER_PORT=3600
 # MESSENGER_ADMIN_TOKEN ne sont plus lus : le serveur refuse de démarrer s'ils sont posés.
 # Mot de passe perdu : npx @imenam/mcp-messenger --reset-password
 
-# Rate limiting (par IP).
-MESSENGER_RATE_LIMIT_MAX=600
-MESSENGER_RATE_LIMIT_WINDOW_MINUTES=15
-
-# Purge automatique de la corbeille (0 = désactivée).
-MESSENGER_TRASH_RETENTION_DAYS=30
-
-# === Mode MCP (côté agent) : `mcp-messenger` ==============================
-
-# Adresse FIXE de l'agent — à laisser vide dans la plupart des cas.
-# Vide : chaque session reçoit sa propre boîte (`box_…`), allouée au démarrage. Deux
-#   sessions ouvertes sur le même projet ne partagent donc pas leur courrier. L'agent
-#   donne son adresse avec `whoami`, et reprend une boîte existante avec
-#   `attach_to_mailbox`.
-# Renseignée : toutes les sessions utilisant cette configuration partagent cette boîte.
-# MESSENGER_AGENT_ID=
-
-# Adresse du serveur boîte aux lettres (http ou https, local ou distant).
-MESSENGER_SERVER_URL=http://127.0.0.1:3600
-
+# Rate limiting (par IP).
+MESSENGER_RATE_LIMIT_MAX=600
+MESSENGER_RATE_LIMIT_WINDOW_MINUTES=15
+
+# Purge automatique de la corbeille (0 = désactivée).
+MESSENGER_TRASH_RETENTION_DAYS=30
+
+# === Mode MCP (côté agent) : `mcp-messenger` ==============================
+
+# Adresse FIXE de l'agent — à laisser vide dans la plupart des cas.
+# Vide : chaque session reçoit sa propre boîte (`box_…`), allouée au démarrage. Deux
+#   sessions ouvertes sur le même projet ne partagent donc pas leur courrier. L'agent
+#   donne son adresse avec `whoami`, et reprend une boîte existante avec
+#   `attach_to_mailbox`.
+# Renseignée : toutes les sessions utilisant cette configuration partagent cette boîte.
+# MESSENGER_AGENT_ID=
+
+# Adresse du serveur boîte aux lettres (http ou https, local ou distant).
+MESSENGER_SERVER_URL=http://127.0.0.1:3600
+
 # Clé API créée dans la console (onglet Clés API) — obligatoire.
 MESSENGER_API_KEY=mk_change-me
 
-# Métadonnées publiées dans l'annuaire des agents (facultatif). Le nom d'agent ne sert
-# qu'avec une clé valable pour tous les agents : une clé liée à un agent donne le sien.
-# MESSENGER_AGENT_NAME=Planner
-# MESSENGER_AGENT_DESCRIPTION=Agent de planification, répond aux demandes de découpage de tâches.
-
-# Délai maximal d'un appel HTTP vers le serveur (ms).
-MESSENGER_TIMEOUT_MS=15000
-
-# Reprise de la boîte d'une session interrompue puis relancée.
-# auto (défaut) : la session retrouve sa boîte quand c'est certain (l'hôte a redonné le
-#   même identifiant de session) ou sans ambiguïté (une seule boîte du projet n'est plus
-#   tenue par personne, et elle a servi).
-# ask : rien n'est repris tout seul ; `whoami` présente les boîtes en attente, l'agent en
-#   rattache une avec `attach_to_mailbox`.
-# off : chaque session repart d'une boîte neuve.
-# Une boîte tenue par une session vivante n'est jamais reprise, quel que soit le réglage.
-# MESSENGER_RESUME=auto
-
-# Identifiant de la session hôte, celui qui relie une session reprise à celle qu'elle
-# continue. Inutile à renseigner : il est lu dans l'environnement hérité de l'hôte
-# (CLAUDE_CODE_SESSION_ID et équivalents). À poser soi-même pour des sessions lancées par
-# script. Il n'est jamais écrit sur le disque en clair, seule son empreinte l'est.
-# MESSENGER_SESSION_KEY=
+# Métadonnées publiées dans l'annuaire des agents (facultatif). Elles ne servent qu'avec
+# une clé valable pour tous les agents : une clé liée à un agent porte son nom et sa
+# description, et refuse d'autres valeurs.
+# MESSENGER_AGENT_NAME=Planner
+# MESSENGER_AGENT_DESCRIPTION=Agent de planification, répond aux demandes de découpage de tâches.
+
+# Délai maximal d'un appel HTTP vers le serveur (ms).
+MESSENGER_TIMEOUT_MS=15000
+
+# Reprise de la boîte d'une session interrompue puis relancée.
+# auto (défaut) : la session retrouve sa boîte quand c'est certain (l'hôte a redonné le
+#   même identifiant de session) ou sans ambiguïté (une seule boîte du projet n'est plus
+#   tenue par personne, et elle a servi).
+# ask : rien n'est repris tout seul ; `whoami` présente les boîtes en attente, l'agent en
+#   rattache une avec `attach_to_mailbox`.
+# off : chaque session repart d'une boîte neuve.
+# Une boîte tenue par une session vivante n'est jamais reprise, quel que soit le réglage.
+# MESSENGER_RESUME=auto
+
+# Identifiant de la session hôte, celui qui relie une session reprise à celle qu'elle
+# continue. Inutile à renseigner : il est lu dans l'environnement hérité de l'hôte
+# (CLAUDE_CODE_SESSION_ID et équivalents). À poser soi-même pour des sessions lancées par
+# script. Il n'est jamais écrit sur le disque en clair, seule son empreinte l'est.
+# MESSENGER_SESSION_KEY=

package/README.md

@@ -72,12 +72,15 @@ Trois invariants, non négociables et vérifiés par les tests :
 
 Une clé se crée dans la console avec un nom, une portée et une durée :
 
-- **Un seul agent** : la clé porte un nom d'agent (par exemple `Documentor Dev`). Les
-  boîtes ouvertes avec elle prennent ce nom — `MESSENGER_AGENT_NAME` devient inutile côté
-  client, et un autre nom y est refusé — et elle n'ouvre que les boîtes de cet agent.
+- **Un seul agent** : la clé porte le nom de l'agent (par exemple `Documentor Dev`) et,
+  si on le souhaite, sa description. Les boîtes ouvertes avec elle prennent ce nom et
+  cette description, et elle n'ouvre que les boîtes de cet agent. `MESSENGER_AGENT_NAME`
+  et `MESSENGER_AGENT_DESCRIPTION` restent vides côté client : une autre valeur y fait
+  refuser l'enregistrement de la boîte. Modifier la description dans la console la
+  reporte sur les boîtes déjà ouvertes avec la clé.
 - **Tous les agents** : la clé ouvre toutes les boîtes ; chaque client donne alors son nom
-  dans `MESSENGER_AGENT_NAME`. C'est un mode « cercle de confiance », pour les sessions
-  d'une même personne.
+  et sa description dans `MESSENGER_AGENT_NAME` et `MESSENGER_AGENT_DESCRIPTION`. C'est
+  un mode « cercle de confiance », pour les sessions d'une même personne.
 - **Durée** : 30 jours, 90 jours, 1 an ou sans échéance. La liste signale une clé qui expire
   dans les 7 jours ; on la prolonge depuis son détail.
 
@@ -138,6 +141,10 @@ Au démarrage, le MCP s'enregistre dans l'annuaire du serveur ; si le serveur es
 momentanément injoignable, la session MCP démarre quand même et l'enregistrement se fera au
 premier appel réussi.
 
+Un refus du serveur, lui, arrête le démarrage avec son motif : clé inconnue, révoquée ou
+expirée, nom ou description d'agent qui contredit une clé liée à un agent. Il ne passerait
+pas en réessayant, c'est la configuration qui est à corriger.
+
 ### 3. Écrire à un autre agent
 
 L'agent A appelle `send_message` avec `to: ["coder"]`, l'agent B voit le message via
@@ -323,7 +330,7 @@ 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` |
+| Posé par | la clé API liée à un agent, sinon la configuration du client (`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` |
 
@@ -650,7 +657,7 @@ dans la base. `MESSENGER_TOKEN`, `MESSENGER_AGENT_TOKENS` et `MESSENGER_ADMIN_TO
 | `MESSENGER_SERVER_URL` | ✅ | `http://` ou `https://`, local ou distant |
 | `MESSENGER_API_KEY` | ✅ | Clé API créée dans la console, présentée sur chaque appel |
 | `MESSENGER_AGENT_NAME` | — | Nom de l'agent, pour une clé valable pour tous les agents. Une clé liée à un agent donne le sien, et en refuse un autre |
-| `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour ses correspondants |
+| `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour une clé valable pour tous les agents. Une clé liée à un agent porte la sienne, et en refuse une autre |
 | `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`) |
 
@@ -699,8 +706,8 @@ cet agent (403 sinon). Les routes `/admin/*` n'acceptent que la session de la co
 | `POST` | `/admin/links` | Lie deux boîtes (`mailboxes: [a, b]`, `note?`) — 404 si l'une est inconnue, 409 si elles sont déjà liées |
 | `DELETE` | `/admin/links/:id` | Supprime une liaison |
 | `GET` | `/admin/keys` | Clés API, sans leur secret : début et fin, agent, échéance, dernier usage, état (`active`, `expired`, `revoked`) |
-| `POST` | `/admin/keys` | Crée une clé (`name`, `agent_name` ou `null` pour tous les agents, `lifetime_days` ou `null`) — rend le secret, une seule fois |
-| `GET` `PATCH` | `/admin/keys/:id` | Détail d'une clé et boîtes ouvertes avec elle · renommer (`name`) |
+| `POST` | `/admin/keys` | Crée une clé (`name`, `agent_name` ou `null` pour tous les agents, `agent_description?` pour une clé liée, `lifetime_days` ou `null`) — rend le secret, une seule fois |
+| `GET` `PATCH` | `/admin/keys/:id` | Détail d'une clé et boîtes ouvertes avec elle · renommer (`name`), changer la description de l'agent (`agent_description`, reportée sur ses boîtes) |
 | `POST` | `/admin/keys/:id/extend` | Repousse l'échéance de `days` jours, ou la retire (`days: null`) |
 | `POST` | `/admin/keys/:id/rotate` | Nouvelle clé aux mêmes réglages ; l'ancienne reste acceptée 24 h |
 | `POST` | `/admin/keys/:id/revoke` | Révoque la clé, refusée dès l'appel suivant |
@@ -796,7 +803,7 @@ test/                   # store, config, API HTTP, outils MCP, binaire réel
 
 ### Tests
 
-379 tests couvrant : le compte de la console (création gardée par le code d'installation,
+382 tests couvrant : le compte de la console (création gardée par le code d'installation,
 connexion et limitation des essais, changement de mot de passe qui ferme les autres
 sessions, fermeture d'une session), les clés API (montrées une fois, liées à un agent ou
 non, prolongées, remplacées, révoquées, expirées) et leurs écrans dans la console, les suppressions de boîtes commandées depuis la console — une boîte

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

@@ -17,6 +17,8 @@ export interface ApiKey {
     suffix: string;
     /** Agent dont la clé ouvre les boîtes ; null = tous les agents. */
     agent_name: string | null;
+    /** Description de cet agent, portée par la clé ; seule une clé liée à un agent en a une. */
+    agent_description: string | null;
     created_at: string;
     created_by: string | null;
     expires_at: string | null;
@@ -93,6 +95,7 @@ export declare class AccessStore {
     createApiKey(input: {
         name: string;
         agentName: string | null;
+        agentDescription?: string | null;
         lifetimeDays: number | null;
         createdBy: string | null;
         secret: string;
@@ -101,6 +104,11 @@ export declare class AccessStore {
     getApiKey(id: string): ApiKey | null;
     private requireKey;
     renameApiKey(id: string, name: string): ApiKey;
+    /**
+     * Change la description de l'agent portée par une clé liée à un agent, et la reporte sur
+     * les boîtes déjà ouvertes avec elle. null l'efface de la clé, pas des boîtes.
+     */
+    setApiKeyAgentDescription(id: string, description: string | null): ApiKey;
     /**
      * Repousse l'expiration de `days` jours, comptés depuis l'échéance encore à venir ou,
      * pour une clé déjà expirée, depuis maintenant. `null` retire toute échéance.
@@ -108,7 +116,7 @@ export declare class AccessStore {
     extendApiKey(id: string, days: number | null): ApiKey;
     revokeApiKey(id: string): ApiKey;
     /**
-     * Remplace une clé : la nouvelle reprend le nom, l'agent et la durée de validité de
+     * Remplace une clé : la nouvelle reprend le nom, l'agent, sa description et la durée de validité de
      * l'ancienne ; l'ancienne reste acceptée `graceMs` encore, au plus jusqu'à son échéance.
      */
     rotateApiKey(id: string, secret: string, createdBy: string | null, graceMs: number): {

package/dist/src/core/access-store.js

@@ -4,7 +4,7 @@ import { MessengerError } from "./errors.js";
 /** Une date de dernier usage n'est réécrite qu'au-delà de ce délai : pas une écriture par requête. */
 const TOUCH_INTERVAL_MS = 60_000;
 const DAY_MS = 24 * 60 * 60 * 1000;
-const KEY_COLUMNS = `k.id, k.name, k.prefix, k.suffix, k.agent_name, k.created_at, k.created_by, k.expires_at,
+const KEY_COLUMNS = `k.id, k.name, k.prefix, k.suffix, k.agent_name, k.agent_description, k.created_at, k.created_by, k.expires_at,
   k.lifetime_days, k.revoked_at, k.last_used_at, k.last_used_ip,
   (SELECT COUNT(*) FROM mailbox_keys mk JOIN agents a ON a.id = mk.mailbox WHERE mk.api_key_id = k.id) AS mailboxes`;
 export class AccessStore {
@@ -41,6 +41,7 @@ export class AccessStore {
         prefix        TEXT NOT NULL,
         suffix        TEXT NOT NULL,
         agent_name    TEXT,
+        agent_description TEXT,
         created_at    TEXT NOT NULL,
         created_by    TEXT,
         expires_at    TEXT,
@@ -183,9 +184,9 @@ export class AccessStore {
         const id = newId("key");
         const visible = input.secret.startsWith(API_KEY_PREFIX) ? API_KEY_PREFIX.length : 0;
         this.db
-            .prepare(`INSERT INTO api_keys (id, name, secret_hash, prefix, suffix, agent_name, created_at, created_by, expires_at, lifetime_days)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(id, input.name, digestSecret(input.secret), input.secret.slice(0, visible + 4), input.secret.slice(-4), input.agentName, this.iso(), input.createdBy, input.lifetimeDays === null ? null : this.iso(input.lifetimeDays * DAY_MS), input.lifetimeDays);
+            .prepare(`INSERT INTO api_keys (id, name, secret_hash, prefix, suffix, agent_name, agent_description, created_at, created_by, expires_at, lifetime_days)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, input.name, digestSecret(input.secret), input.secret.slice(0, visible + 4), input.secret.slice(-4), input.agentName, input.agentDescription ?? null, this.iso(), input.createdBy, input.lifetimeDays === null ? null : this.iso(input.lifetimeDays * DAY_MS), input.lifetimeDays);
         return this.getApiKey(id);
     }
     listApiKeys() {
@@ -206,6 +207,25 @@ export class AccessStore {
         this.db.prepare("UPDATE api_keys SET name = ? WHERE id = ?").run(name, id);
         return this.getApiKey(id);
     }
+    /**
+     * Change la description de l'agent portée par une clé liée à un agent, et la reporte sur
+     * les boîtes déjà ouvertes avec elle. null l'efface de la clé, pas des boîtes.
+     */
+    setApiKeyAgentDescription(id, description) {
+        const key = this.requireKey(id);
+        if (!key.agent_name) {
+            throw new MessengerError("only a key bound to an agent carries an agent description", 400);
+        }
+        this.db.transaction(() => {
+            this.db.prepare("UPDATE api_keys SET agent_description = ? WHERE id = ?").run(description, id);
+            if (description !== null) {
+                this.db
+                    .prepare("UPDATE agents SET agent_description = ? WHERE id IN (SELECT mailbox FROM mailbox_keys WHERE api_key_id = ?)")
+                    .run(description, id);
+            }
+        })();
+        return this.getApiKey(id);
+    }
     /**
      * Repousse l'expiration de `days` jours, comptés depuis l'échéance encore à venir ou,
      * pour une clé déjà expirée, depuis maintenant. `null` retire toute échéance.
@@ -227,7 +247,7 @@ export class AccessStore {
         return this.getApiKey(id);
     }
     /**
-     * Remplace une clé : la nouvelle reprend le nom, l'agent et la durée de validité de
+     * Remplace une clé : la nouvelle reprend le nom, l'agent, sa description et la durée de validité de
      * l'ancienne ; l'ancienne reste acceptée `graceMs` encore, au plus jusqu'à son échéance.
      */
     rotateApiKey(id, secret, createdBy, graceMs) {
@@ -238,6 +258,7 @@ export class AccessStore {
             const key = this.createApiKey({
                 name: old.name,
                 agentName: old.agent_name,
+                agentDescription: old.agent_description,
                 lifetimeDays: old.lifetime_days,
                 createdBy,
                 secret,

package/dist/src/mcp/start.js

@@ -1,7 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { loadAgentConfig } from "../config.js";
+import { ConfigError, loadAgentConfig } from "../config.js";
 import { MessengerClient, MessengerClientError } from "../client/messenger-client.js";
 import { removeOwnHandoffs } from "../cli/watch-handoff.js";
 import { newId } from "../core/ids.js";
@@ -190,13 +190,23 @@ export async function runMcpMode() {
     const config = loadAgentConfig();
     const client = new MessengerClient(config);
     // Un serveur momentanément injoignable ne doit pas empêcher la session MCP de démarrer :
-    // l'agent verra l'erreur au premier outil appelé, et pourra réessayer.
+    // l'agent verra l'erreur au premier outil appelé, et pourra réessayer. Un refus du
+    // serveur, lui, ne passera pas en réessayant : la clé ou la configuration est à corriger,
+    // et le démarrage s'arrête en le disant.
     try {
         const identity = await resolveIdentity(client, config);
         logger.info(`mailbox \`${identity.mailbox}\` ready on ${config.serverUrl}${describeIdentity(identity, config)}`);
     }
     catch (error) {
-        logger.warn(`could not reach ${config.serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        if (error instanceof MessengerClientError && (error.status === 401 || error.status === 403)) {
+            throw new ConfigError(`the messenger server at ${config.serverUrl} refused this configuration: ${error.message}`);
+        }
+        if (error instanceof MessengerClientError && error.status !== undefined) {
+            logger.warn(`mailbox registration failed on ${config.serverUrl} (HTTP ${error.status}): ${error.message}`);
+        }
+        else {
+            logger.warn(`could not reach ${config.serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     // Tant que ce battement continue, la boîte de cette session n'est reprise par personne.
     // `unref` : c'est une trace, pas une raison de garder le processus en vie.

package/dist/src/server/app.js

@@ -119,13 +119,32 @@ const passwordChangeSchema = z.object({
 });
 /** Durée de validité d'une clé, en jours ; null = sans échéance. */
 const lifetimeSchema = z.number().int().min(1).max(3650).nullable();
-const keyCreateSchema = z.object({
+/** Description de l'agent portée par une clé : une chaîne vide l'efface. */
+const agentDescriptionSchema = z
+    .string()
+    .trim()
+    .max(2000)
+    .nullable()
+    .transform((value) => value || null);
+const keyCreateSchema = z
+    .object({
     name: z.string().trim().min(1).max(200),
     /** Agent dont la clé ouvre les boîtes ; null = tous les agents. */
     agent_name: z.string().trim().min(1).max(200).nullable(),
+    agent_description: agentDescriptionSchema.optional(),
     lifetime_days: lifetimeSchema,
+})
+    .refine((input) => input.agent_name !== null || !input.agent_description, {
+    message: "only a key bound to an agent carries an agent description",
+});
+const keyPatchSchema = z
+    .object({
+    name: z.string().trim().min(1).max(200).optional(),
+    agent_description: agentDescriptionSchema.optional(),
+})
+    .refine((input) => input.name !== undefined || input.agent_description !== undefined, {
+    message: "provide `name` and/or `agent_description`",
 });
-const keyRenameSchema = z.object({ name: z.string().trim().min(1).max(200) });
 const keyExtendSchema = z.object({ days: lifetimeSchema });
 const adminThreadsSchema = z.object({
     search: z.string().trim().min(1).optional(),
@@ -489,6 +508,7 @@ export function createApp({ store, config, setup = new SetupGate(store.access) }
         const key = access.createApiKey({
             name: input.name,
             agentName: input.agent_name,
+            agentDescription: input.agent_description ?? null,
             lifetimeDays: input.lifetime_days,
             createdBy: req.consoleUser.username,
             secret,
@@ -504,8 +524,12 @@ export function createApp({ store, config, setup = new SetupGate(store.access) }
         res.json({ key, mailboxes: access.mailboxesForKey(id) });
     });
     admin.patch("/keys/:id", (req, res) => {
-        const input = keyRenameSchema.parse(req.body ?? {});
-        res.json({ key: access.renameApiKey(String(req.params.id), input.name) });
+        const input = keyPatchSchema.parse(req.body ?? {});
+        const id = String(req.params.id);
+        let key = input.name !== undefined ? access.renameApiKey(id, input.name) : null;
+        if (input.agent_description !== undefined)
+            key = access.setApiKeyAgentDescription(id, input.agent_description);
+        res.json({ key });
     });
     admin.post("/keys/:id/extend", (req, res) => {
         const input = keyExtendSchema.parse(req.body ?? {});
@@ -550,17 +574,24 @@ export function createApp({ store, config, setup = new SetupGate(store.access) }
         if (input.fresh && store.getAgent(req.agentId)) {
             throw new MessengerError(`mailbox already exists: ${req.agentId}`, 409);
         }
-        // Une clé liée à un agent donne son nom à la boîte. Un autre nom venu de la
-        // configuration du client est une erreur de réglage, signalée plutôt que corrigée.
+        // Une clé liée à un agent donne son nom et sa description à la boîte. Une autre valeur
+        // venue de la configuration du client est une erreur de réglage, signalée plutôt que
+        // corrigée.
         const key = req.apiKey;
-        if (key.agent_name && input.agent_name && input.agent_name !== key.agent_name) {
-            throw new MessengerError(`this API key is bound to agent "${key.agent_name}": remove MESSENGER_AGENT_NAME from the client ` +
-                `configuration, or set it to "${key.agent_name}"`, 403);
+        if (key.agent_name) {
+            if (input.agent_name && input.agent_name !== key.agent_name) {
+                throw new MessengerError(`this API key is bound to agent "${key.agent_name}": remove MESSENGER_AGENT_NAME from the client ` +
+                    `configuration, or set it to "${key.agent_name}"`, 403);
+            }
+            if (input.agent_description && input.agent_description !== key.agent_description) {
+                throw new MessengerError(`this API key carries the description of agent "${key.agent_name}": remove MESSENGER_AGENT_DESCRIPTION ` +
+                    "from the client configuration, and edit the description in the web console", 403);
+            }
         }
         const agent = store.ensureAgent(req.agentId, {
             registered: true,
             agent_name: key.agent_name ?? input.agent_name ?? null,
-            agent_description: input.agent_description ?? null,
+            agent_description: key.agent_name ? key.agent_description : (input.agent_description ?? null),
             // Un client antérieur à la séparation agent / boîte n'envoie que ces deux-là.
             display_name: input.display_name ?? null,
             description: input.description ?? null,

package/dist/src/server/ui/app.js

@@ -2695,6 +2695,15 @@ function formField(label, control, hint) {
   return wrapper;
 }
 
+function textArea(value, placeholder) {
+  const area = document.createElement("textarea");
+  area.value = value || "";
+  area.rows = 2;
+  area.maxLength = 2000;
+  if (placeholder) area.placeholder = placeholder;
+  return area;
+}
+
 function textInput(value, options = {}) {
   const input = document.createElement("input");
   input.type = options.type || "text";
@@ -2978,11 +2987,15 @@ function choiceChips(options, selected, onPick) {
 
 function openKeyCreate() {
   keysView.detailId = null;
-  const form = { name: "", scope: "one", agent: "", lifetime: KEY_LIFETIMES[1] };
+  const form = { name: "", scope: "one", agent: "", description: "", lifetime: KEY_LIFETIMES[1] };
   const names = knownAgentNames();
 
   const nameInput = textInput("", { placeholder: "Poste, machine ou usage", autocomplete: "off" });
   const agentInput = textInput("", { placeholder: "Nom de l'agent", autocomplete: "off", list: "key-agent-names" });
+  const descriptionInput = textArea("", "À quoi sert cet agent, pour ses correspondants");
+  descriptionInput.addEventListener("input", () => {
+    form.description = descriptionInput.value;
+  });
   const datalist = node("datalist");
   datalist.id = "key-agent-names";
   for (const name of names) {
@@ -3027,11 +3040,14 @@ function openKeyCreate() {
       box.append(agentMark, agentInput, newTag);
       updateAgentMark();
       agentField.appendChild(box);
+      const description = node("span", "field-input field-input--area");
+      description.appendChild(descriptionInput);
+      agentField.appendChild(description);
       agentField.appendChild(
         node(
           "span",
           "field-hint",
-          "Les sessions ouvertes avec cette clé portent ce nom d'agent : MESSENGER_AGENT_NAME n'a plus à être posé côté client."
+          "Le nom et la description s'appliquent à toutes les sessions ouvertes avec cette clé : rien à poser côté client."
         )
       );
     } else {
@@ -3071,7 +3087,7 @@ function openKeyCreate() {
       datalist
     );
     // Le volet se reconstruit à chaque choix : la saisie en cours garde le curseur.
-    if (focused === agentInput || focused === nameInput) focused.focus();
+    if (focused === agentInput || focused === nameInput || focused === descriptionInput) focused.focus();
     create.disabled = !form.name.trim() || (form.scope === "one" && !form.agent.trim());
   }
 
@@ -3097,6 +3113,7 @@ function openKeyCreate() {
       const created = await post("/admin/keys", {
         name: form.name.trim(),
         agent_name: form.scope === "one" ? form.agent.trim() : null,
+        ...(form.scope === "one" && form.description.trim() ? { agent_description: form.description.trim() } : {}),
         lifetime_days: form.lifetime.days,
       });
       renderKeyReveal(created.key, created.secret, null);
@@ -3247,6 +3264,7 @@ async function openKeyDetail(id) {
 
 function renderKeyDetail({ key, mailboxes }) {
   let renaming = false;
+  let describing = false;
   let extendOpen = false;
   const error = node("p", "form-banner");
   error.hidden = true;
@@ -3368,6 +3386,7 @@ function renderKeyDetail({ key, mailboxes }) {
       list.appendChild(cell);
     };
     add("Agent autorisé", keyAgent(key));
+    if (key.agent_name) add("Description", descriptionCell());
     add("Créée", `${formatDay(key.created_at)}${key.created_by ? ` par ${key.created_by}` : ""}`);
     add(
       "Dernière utilisation",
@@ -3379,6 +3398,60 @@ function renderKeyDetail({ key, mailboxes }) {
     return list;
   }
 
+  /** Description de l'agent, modifiable sur place : Entrée enregistre, Échap annule. */
+  function descriptionCell() {
+    if (!describing) {
+      const value = node("span", key.agent_description ? "props-value" : "props-value key-muted", key.agent_description || "aucune");
+      const edit = node("button", "btn btn--icon btn--ghost props-edit");
+      edit.type = "button";
+      edit.title = "Modifier la description";
+      edit.setAttribute("aria-label", "Modifier la description de l'agent");
+      edit.appendChild(icon("pencil"));
+      edit.addEventListener("click", () => {
+        describing = true;
+        render();
+      });
+      return [value, edit];
+    }
+    const area = textArea(key.agent_description, "À quoi sert cet agent, pour ses correspondants");
+    area.className = "inline-area";
+    let saved = false;
+    const save = async () => {
+      if (saved) return;
+      saved = true;
+      const description = area.value.trim();
+      if (description === (key.agent_description || "")) {
+        describing = false;
+        render();
+        return;
+      }
+      try {
+        await patch(`/admin/keys/${encodeURIComponent(key.id)}`, { agent_description: description || null });
+        await reload();
+      } catch (failure) {
+        saved = false;
+        fail(failure);
+      }
+    };
+    area.addEventListener("keydown", (event) => {
+      if (event.key === "Enter" && !event.shiftKey) {
+        event.preventDefault();
+        save();
+      }
+      if (event.key === "Escape") {
+        // Échap referme la saisie, pas le volet.
+        event.preventDefault();
+        event.stopPropagation();
+        saved = true;
+        describing = false;
+        render();
+      }
+    });
+    area.addEventListener("blur", save);
+    setTimeout(() => area.focus(), 0);
+    return [area];
+  }
+
   function boxes() {
     const section = node("section", "drawer-section");
     const head = node("div", "drawer-section-head");

package/dist/src/server/ui/styles.css

@@ -2780,6 +2780,43 @@ body {
   gap: 10px;
 }
 
+.field-input--area {
+  height: auto;
+  margin-top: 12px;
+  padding: 8px 12px;
+}
+
+.field-input textarea,
+.inline-area {
+  flex: 1;
+  min-width: 0;
+  border: 0;
+  background: none;
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.4;
+  color: var(--text);
+  resize: vertical;
+  outline: none;
+}
+
+.inline-area {
+  width: 100%;
+  padding: 6px 10px;
+  border: 1px solid var(--accent);
+  border-radius: var(--radius);
+  background: var(--panel);
+}
+
+.props-value {
+  line-height: 1.4;
+}
+
+.props-edit {
+  flex: none;
+  padding: 4px;
+}
+
 .field-tag {
   font-size: 12px;
   color: var(--accent);

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@imenam/mcp-messenger",
-  "version": "1.0.33",
-  "main": "dist/src/index.js",
-  "scripts": {
-    "test": "npm run build && vitest run",
-    "build": "tsc && node scripts/copy-assets.js",
-    "start": "node dist/src/index.js",
-    "serve": "node dist/src/index.js --server",
-    "prepublishOnly": "npm run build",
-    "release": "npm version patch && npm publish && git push --follow-tags",
-    "typecheck": "tsc --noEmit",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "agent",
-    "messaging",
-    "mailbox",
-    "agent-to-agent"
-  ],
-  "author": "Matthieu Pesnot-Pin <matthieupin@gmail.com>",
-  "license": "ISC",
-  "description": "Cross-platform agent-to-agent messaging: an MCP mailbox client plus its HTTP mailbox server.",
-  "type": "module",
-  "bin": {
-    "mcp-messenger": "dist/src/index.js"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "better-sqlite3": "^12.11.1",
-    "dotenv": "^17.4.2",
-    "express": "^5.2.1",
-    "express-rate-limit": "^8.7.0",
-    "helmet": "^8.3.0",
-    "zod": "^4.5.4"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/express": "^5.0.6",
-    "@types/node": "^22.20.1",
-    "@vitest/coverage-v8": "^3.2.7",
-    "jsdom": "^29.1.1",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.7"
-  },
-  "files": [
-    "dist/src",
-    "README.md",
-    ".env.example",
-    "LICENSE"
-  ]
-}
+{
+  "name": "@imenam/mcp-messenger",
+  "version": "1.0.35",
+  "main": "dist/src/index.js",
+  "scripts": {
+    "test": "npm run build && vitest run",
+    "build": "tsc && node scripts/copy-assets.js",
+    "start": "node dist/src/index.js",
+    "serve": "node dist/src/index.js --server",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "typecheck": "tsc --noEmit",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "messaging",
+    "mailbox",
+    "agent-to-agent"
+  ],
+  "author": "Matthieu Pesnot-Pin <matthieupin@gmail.com>",
+  "license": "ISC",
+  "description": "Cross-platform agent-to-agent messaging: an MCP mailbox client plus its HTTP mailbox server.",
+  "type": "module",
+  "bin": {
+    "mcp-messenger": "dist/src/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "better-sqlite3": "^12.11.1",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.7.0",
+    "helmet": "^8.3.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "^5.0.5",
+    "jsdom": "^29.1.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    ".env.example",
+    "LICENSE"
+  ]
+}