@imenam/mcp-messenger 1.0.28 → 1.0.30

package/README.md

@@ -136,11 +136,10 @@ enable_notifications()      → retourne immédiatement, ne bloque rien
   Last step — call the Monitor tool now, with exactly these arguments:
     command:     npx -y @imenam/mcp-messenger --watch box_9f2c4a01b3d7e5f8
     description: Incoming messenger messages
-    persistent:  true
+    timeout_ms:  1800000
 ```
 
-L'agent recopie ces trois arguments dans l'outil `Monitor` de son hôte, et c'est fini pour la
-session. Le veilleur tourne en fond, tient une attente longue sur `/api/wait`, et écrit **une
+L'agent recopie ces trois arguments dans l'outil `Monitor` de son hôte. Le veilleur tourne en fond, tient une attente longue sur `/api/wait`, et écrit **une
 ligne par message** sur sa sortie standard :
 
 ```
@@ -149,6 +148,13 @@ ligne par message** sur sa sortie standard :
 
 Chaque ligne réveille l'agent, qui appelle `read_message` s'il décide de traiter le message.
 
+**Réarmer à l'expiration.** Claude Code arrête tout `Monitor` au bout de 30 minutes au plus,
+quelle que soit la durée demandée, et prévient l'agent. Ce minuteur appartient à l'hôte : le
+veilleur ne peut ni le prolonger ni le remettre à zéro. L'agent relance donc le même appel
+`Monitor` à chaque expiration, sans repasser par `enable_notifications` — la réponse de cet
+outil, les instructions du serveur et le bloc `CLAUDE.md` le lui disent. Le délai de grâce
+décrit plus bas couvre l'intervalle : `whoami` reste à « armed » pendant le réarmement.
+
 **Pourquoi deux appels et pas un.** Armer un réveil, c'est ouvrir un canal vers la boucle de
 la session hôte. Un serveur MCP ne peut pas le faire seul : `Monitor` est un outil de l'hôte,
 seul le modèle peut l'appeler. `enable_notifications` fait donc tout le reste — il connaît
@@ -205,10 +211,11 @@ description dit « mailbox address ».
 | `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é ; `with_mailbox` ne garde que celles partagées avec une boîte |
 | `list_agents` | Annuaire groupé par agent : un projet, ses sessions ; `agent_name` déplie un groupe. 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`) |
+| `send_message` | Écrire à un agent — un seul destinataire par message (`to`, `priority`, `reply_to`, `thread_name`, `attachments`) |
 | `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 |
+| `read_message` | Lire un message en entier, pièces jointes listées ; le marque lu par défaut |
 | `get_thread` | Relire toute une conversation, du plus ancien au plus récent |
+| `save_attachment` | Écrire une pièce jointe sur le disque de la machine (`attachment_id`, `path`, `overwrite`) et rendre son chemin |
 | `mark_messages` | Marquer lu / non lu, suivi / non suivi |
 | `move_messages` | Classer dans un dossier |
 | `delete_messages` | Corbeille, ou suppression définitive (`permanent: true`) |
@@ -225,6 +232,16 @@ elle-même. Pour toucher plusieurs agents, on leur envoie un message chacun, dan
 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.
 
+**Pièces jointes** — `send_message` accepte `attachments: [{ path, name? }]` : le processus
+MCP lit chaque fichier sur la machine de l'agent qui écrit et l'envoie avec le message.
+Au plus 10 fichiers, 10 Mo chacun et 25 Mo au total ; un fichier absent ou trop gros fait
+échouer l'envoi. Le type MIME est déduit de l'extension, `name` renomme le fichier pour le
+destinataire. Celui-ci voit la liste sous le message (`att_…`, nom, type, taille) et
+récupère un fichier avec `save_attachment` : dans le répertoire donné sous son propre nom,
+au chemin de fichier donné, ou par défaut dans le dossier temporaire du système. Un fichier
+existant n'est remplacé qu'avec `overwrite: true`. Les pièces jointes sont stockées dans la
+base avec le message et disparaissent avec sa dernière copie.
+
 **Dossiers système** — toujours présents, non supprimables : `inbox`, `sent`, `archive`,
 `trash`. Les dossiers personnalisés sont propres à chaque boîte.
 
@@ -457,7 +474,9 @@ correspondants et l'état de lecture :
   écrit ne peut devenir une balise, et seuls les liens `http`, `https` et `mailto` sont
   suivis. Une image n'est jamais chargée, elle est montrée par son intitulé et son lien.
   Les aperçus, eux, sont débarrassés de leur syntaxe par le serveur : ils tiennent sur une
-  ligne, où un dièse ou une paire d'astérisques ne serait que du bruit ;
+  ligne, où un dièse ou une paire d'astérisques ne serait que du bruit. **Les pièces
+  jointes** suivent le corps d'un message ouvert, une par lien, avec leur nom et leur
+  taille ; un clic les télécharge, jamais elles ne s'ouvrent dans la console ;
 - **les détails d'un message**, dans une modale ouverte par l'icône d'information au bout
   de sa ligne : l'objet, le nom et l'identifiant du fil, les identifiants, la date, la
   priorité, les deux noms et l'adresse de chaque boîte, et le tableau de distribution
@@ -585,12 +604,13 @@ la console (cookie), qui elle n'ouvre rien d'autre.
 | `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`) |
-| `POST` | `/api/messages` | Envoyer un message |
+| `POST` | `/api/messages` | Envoyer un message ; `attachments: [{ filename, mime_type?, content_base64 }]` |
 | `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) |
 | `POST` | `/api/messages/mark` | Marquer lu / suivi |
 | `POST` | `/api/messages/move` | Déplacer vers un dossier |
 | `POST` | `/api/messages/delete` | Corbeille ou suppression définitive |
+| `GET` | `/api/attachments/:id` | Contenu d'une pièce jointe d'un message de la boîte, en téléchargement |
 | `GET` | `/api/threads` | Fils de la boîte (`unread_only`, `search`, `limit`, `offset`) |
 | `GET` | `/api/threads/:id` | Fil complet, avec son intitulé |
 | `PATCH` | `/api/threads/:id` | Nommer le fil (`title`, `description`) — participants uniquement |
@@ -599,6 +619,7 @@ la console (cookie), qui elle n'ouvre rien d'autre.
 | `GET` | `/admin/overview` · `/admin/messages[/:id]` | Supervision, lecture seule |
 | `GET` | `/admin/threads` | Fils du serveur entier (`agent` — une ou plusieurs adresses séparées par des virgules —, `search`, `unread_only`, `priority`, `limit`, `offset`) |
 | `GET` | `/admin/threads/:id` | Fil complet, corps inclus |
+| `GET` | `/admin/attachments/:id` | Contenu d'une pièce jointe, en téléchargement |
 | `GET` | `/admin/mailboxes/stale` | Boîtes sans activité depuis `before`, avec ce que chacune contient |
 | `GET` | `/admin/mailboxes/created-before` | Boîtes ouvertes avant `created_before`, quelle que soit leur activité |
 | `GET` | `/admin/mailboxes/empty` | Boîtes par lesquelles rien n'est jamais passé, sans critère de date |
@@ -619,8 +640,12 @@ la console (cookie), qui elle n'ouvre rien d'autre.
   d'emprunter l'identité d'un autre agent. À préférer au jeton partagé dès que les agents
   ne se font pas mutuellement confiance.
 - Comparaison des jetons à **temps constant**, en-têtes de sécurité (`helmet`), **rate
-  limiting** par IP, corps JSON limité à 2 Mo, erreurs internes génériques (le détail reste
-  dans les logs).
+  limiting** par IP, corps JSON limité à 2 Mo — sauf l'envoi d'un message, dont la limite
+  couvre ses pièces jointes et ne s'applique qu'une fois l'agent authentifié —, erreurs
+  internes génériques (le détail reste dans les logs).
+- **Pièces jointes** : servies uniquement aux deux boîtes du message (et à la console),
+  toujours en `Content-Disposition: attachment`, jamais affichées en ligne ; leur nom est
+  réduit à sa dernière composante, il ne peut désigner aucun autre répertoire.
 - **Isolation des boîtes** garantie côté serveur : les identifiants de messages fournis par
   un agent sont systématiquement filtrés sur ses propres livraisons.
 - La console web n'insère jamais de HTML fourni par un agent : le corps des messages est
@@ -659,7 +684,8 @@ src/
   index.ts              # point d'entrée : --server, --watch, --help, --version, sinon mode MCP
   config.ts             # lecture et validation des variables d'environnement
   logger.ts             # journalisation sur stderr (stdout est réservé au JSON-RPC)
-  core/store.ts         # SQLite : agents, messages, livraisons, dossiers
+  core/store.ts         # SQLite : agents, messages, livraisons, dossiers, pièces jointes
+  core/attachments.ts   # limites des pièces jointes, en-tête de téléchargement
   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

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

@@ -56,6 +56,10 @@ Au démarrage de la session, avant toute autre chose : appeler \`enable_notifica
 puis armer l'outil \`Monitor\` avec la commande exacte qu'il retourne. Sans cela, aucun
 message ne parviendra à l'agent — il ne l'apprendra qu'en appelant \`list_messages\`.
 
+L'hôte arrête le veilleur au bout de 30 minutes au plus. À chaque expiration signalée,
+le réarmer aussitôt avec le même appel \`Monitor\`, sans repasser par
+\`enable_notifications\`.
+
 Une fois le veilleur armé, ne rien attendre : les messages entrants interrompent l'agent
 d'eux-mêmes, y compris à l'arrêt. \`wait_for_message\` ne sert plus qu'à bloquer
 volontairement sur une réponse précise.

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

@@ -5,6 +5,17 @@ export declare class MessengerClientError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
+/** Pièce jointe à l'envoi, contenu encodé en base64. */
+export interface OutgoingAttachment {
+    filename: string;
+    mime_type: string | null;
+    content_base64: string;
+}
+export interface DownloadedAttachment {
+    filename: string;
+    mime_type: string;
+    data: Buffer;
+}
 export interface WaitResult {
     timed_out: boolean;
     message: Message | null;
@@ -68,9 +79,11 @@ export declare class MessengerClient {
         reply_to?: string | null;
         thread_title?: string | null;
         thread_description?: string | null;
+        attachments?: OutgoingAttachment[];
     }): Promise<SendMessageResult>;
     listMessages(options?: ListMessagesOptions): Promise<MessageSummary[]>;
     getMessage(messageId: string, markRead?: boolean): Promise<Message>;
+    downloadAttachment(attachmentId: string): Promise<DownloadedAttachment>;
     markMessages(messageIds: string[], state: {
         read?: boolean;
         starred?: boolean;
@@ -104,4 +117,7 @@ export declare class MessengerClient {
         watcher?: boolean;
     }): Promise<WaitResult>;
     private request;
+    private send;
+    /** Erreur lisible tirée d'une réponse en échec. */
+    private failure;
 }

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

@@ -1,3 +1,4 @@
+import { filenameFromDisposition } from "../core/attachments.js";
 /** Échec d'un appel au serveur boîte aux lettres (réseau, authentification ou métier). */
 export class MessengerClientError extends Error {
     status;
@@ -105,6 +106,16 @@ export class MessengerClient {
             query: { mark_read: markRead },
         });
     }
+    async downloadAttachment(attachmentId) {
+        const response = await this.send("GET", `/api/attachments/${encodeURIComponent(attachmentId)}`);
+        if (!response.ok)
+            throw await this.failure(response);
+        return {
+            filename: filenameFromDisposition(response.headers.get("content-disposition")) ?? attachmentId,
+            mime_type: response.headers.get("content-type") ?? "application/octet-stream",
+            data: Buffer.from(await response.arrayBuffer()),
+        };
+    }
     async markMessages(messageIds, state) {
         const { updated } = await this.request("POST", "/api/messages/mark", {
             body: { message_ids: messageIds, ...state },
@@ -160,6 +171,13 @@ export class MessengerClient {
         });
     }
     async request(method, routePath, options = {}) {
+        const response = await this.send(method, routePath, options);
+        if (!response.ok)
+            throw await this.failure(response);
+        const text = await response.text();
+        return (text ? safeParse(text) : null);
+    }
+    async send(method, routePath, options = {}) {
         const url = new URL(this.config.serverUrl + routePath);
         for (const [key, value] of Object.entries(options.query ?? {})) {
             if (value === undefined || value === null || value === "")
@@ -171,9 +189,8 @@ export class MessengerClient {
             headers.authorization = `Bearer ${this.config.token}`;
         if (options.body !== undefined)
             headers["content-type"] = "application/json";
-        let response;
         try {
-            response = await fetch(url, {
+            return await fetch(url, {
                 method,
                 headers,
                 body: options.body === undefined ? undefined : JSON.stringify(options.body),
@@ -184,15 +201,15 @@ export class MessengerClient {
             const reason = error instanceof Error ? error.message : String(error);
             throw new MessengerClientError(`cannot reach the messenger server at ${this.config.serverUrl}: ${reason}`);
         }
+    }
+    /** Erreur lisible tirée d'une réponse en échec. */
+    async failure(response) {
         const text = await response.text();
         const payload = text ? safeParse(text) : null;
-        if (!response.ok) {
-            const detail = payload && typeof payload === "object" && "error" in payload
-                ? String(payload.error)
-                : text.slice(0, 300) || response.statusText;
-            throw new MessengerClientError(detail, response.status);
-        }
-        return payload;
+        const detail = payload && typeof payload === "object" && "error" in payload
+            ? String(payload.error)
+            : text.slice(0, 300) || response.statusText;
+        return new MessengerClientError(detail, response.status);
     }
 }
 function safeParse(text) {

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

@@ -0,0 +1,16 @@
+/** Nombre de pièces jointes par message. */
+export declare const MAX_ATTACHMENTS = 10;
+/** Taille d'une pièce jointe, en octets. */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** Taille cumulée des pièces jointes d'un message, en octets. */
+export declare const MAX_ATTACHMENTS_TOTAL_BYTES: number;
+export declare function formatBytes(bytes: number): string;
+/**
+ * En-tête `Content-Disposition` d'un téléchargement.
+ *
+ * Toujours `attachment` : servi en ligne, un fichier HTML ou SVG s'exécuterait dans
+ * l'origine de la console.
+ */
+export declare function contentDisposition(filename: string): string;
+/** Nom de fichier porté par un en-tête produit par `contentDisposition`. */
+export declare function filenameFromDisposition(header: string | null): string | null;

package/dist/src/core/attachments.js

@@ -0,0 +1,28 @@
+/** Nombre de pièces jointes par message. */
+export const MAX_ATTACHMENTS = 10;
+/** Taille d'une pièce jointe, en octets. */
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+/** Taille cumulée des pièces jointes d'un message, en octets. */
+export const MAX_ATTACHMENTS_TOTAL_BYTES = 25 * 1024 * 1024;
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * En-tête `Content-Disposition` d'un téléchargement.
+ *
+ * Toujours `attachment` : servi en ligne, un fichier HTML ou SVG s'exécuterait dans
+ * l'origine de la console.
+ */
+export function contentDisposition(filename) {
+    const ascii = filename.replace(/[^\x20-\x7e]|["\\]/g, "_");
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+/** Nom de fichier porté par un en-tête produit par `contentDisposition`. */
+export function filenameFromDisposition(header) {
+    const encoded = header?.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+    return encoded ? decodeURIComponent(encoded) : null;
+}

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

@@ -1,10 +1,15 @@
 import { EventEmitter } from "node:events";
-import { type AdminThreadSummary, type Agent, type AgentDirectoryEntry, type DeliveryRole, type FolderInfo, type ListMessagesOptions, type ListThreadsOptions, type MailboxStats, type Message, type MessageSummary, type Priority, type SendMessageInput, type SendMessageResult, type ThreadInfo, type ThreadSummary } from "./types.js";
+import { type AdminThreadSummary, type Agent, type AgentDirectoryEntry, type AttachmentInfo, type DeliveryRole, type FolderInfo, type ListMessagesOptions, type ListThreadsOptions, type MailboxStats, type Message, type MessageSummary, type Priority, type SendMessageInput, type SendMessageResult, type ThreadInfo, type ThreadSummary } from "./types.js";
 /** Erreur métier : traduite en 4xx par la couche HTTP, en message d'outil côté MCP. */
 export declare class MessengerError extends Error {
     readonly status: number;
     constructor(message: string, status?: number);
 }
+/** Contenu d'une pièce jointe, avec ses métadonnées. */
+export interface AttachmentContent extends AttachmentInfo {
+    message_id: string;
+    data: Buffer;
+}
 export interface EnsureAgentOptions {
     registered?: boolean;
     /** Identité de l'agent : d'où il vient. Posée par la configuration. */
@@ -55,6 +60,8 @@ export declare class MessageStore extends EventEmitter<StoreEvents> {
     getMessage(agentId: string, messageId: string, markRead?: boolean): Message;
     /** Tous les messages d'un fil visibles par l'agent, du plus ancien au plus récent. */
     getThread(agentId: string, threadId: string): Message[];
+    /** Pièce jointe d'un message livré à cet agent, contenu compris. */
+    getAttachment(agentId: string, attachmentId: string): AttachmentContent;
     getThreadInfo(threadId: string): ThreadInfo | null;
     /**
      * Renomme un fil. Le titre est unique et partagé : les participants parlent du même
@@ -183,6 +190,8 @@ export declare class MessageStore extends EventEmitter<StoreEvents> {
             read: boolean;
         }[];
     };
+    /** Pièce jointe vue du serveur, quelle que soit la boîte. */
+    getAttachmentAdmin(attachmentId: string): AttachmentContent;
     overview(): {
         messages: number;
         threads: number;
@@ -196,8 +205,8 @@ 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;
+    /** Destinataire et pièces jointes de chaque message demandé, par identifiant de message. */
+    private relatedFor;
     private toSummary;
     private toMessage;
     /** Un message sans aucune livraison n'est plus lisible par personne : on le supprime. */

package/dist/src/core/store.js

@@ -2,6 +2,7 @@ import Database from "better-sqlite3";
 import { EventEmitter } from "node:events";
 import fs from "node:fs";
 import path from "node:path";
+import { MAX_ATTACHMENTS, MAX_ATTACHMENTS_TOTAL_BYTES, MAX_ATTACHMENT_BYTES, formatBytes } from "./attachments.js";
 import { newId } from "./ids.js";
 import { DELIVERY_ROLES, SYSTEM_FOLDERS, } from "./types.js";
 /** Erreur métier : traduite en 4xx par la couche HTTP, en message d'outil côté MCP. */
@@ -18,6 +19,9 @@ const MAX_LIMIT = 100;
 const FOLDER_NAME_RE = /^[a-z0-9][a-z0-9 _-]{0,39}$/;
 const THREAD_TITLE_MAX = 200;
 const THREAD_DESCRIPTION_MAX = 2000;
+const FILENAME_MAX = 255;
+const MIME_TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
+const DEFAULT_MIME_TYPE = "application/octet-stream";
 /**
  * Dernière activité d'une boîte : sa dernière connexion, ou le dernier message qui l'a
  * touchée. Une boîte qui ne fait que recevoir reste vivante, alors que `last_seen_at`
@@ -115,6 +119,18 @@ export class MessageStore extends EventEmitter {
         PRIMARY KEY (agent_id, name)
       );
 
+      CREATE TABLE IF NOT EXISTS attachments (
+        id         TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+        position   INTEGER NOT NULL,
+        filename   TEXT NOT NULL,
+        mime_type  TEXT NOT NULL,
+        size       INTEGER NOT NULL,
+        data       BLOB NOT NULL,
+        created_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_attachments_message ON attachments (message_id, position);
       CREATE INDEX IF NOT EXISTS idx_deliveries_mailbox ON deliveries (agent_id, folder, created_at DESC);
       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);
@@ -223,6 +239,7 @@ export class MessageStore extends EventEmitter {
             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");
+        const attachments = normalizeAttachments(input.attachments ?? []);
         let threadId;
         let inReplyTo = null;
         if (input.reply_to) {
@@ -262,6 +279,11 @@ export class MessageStore extends EventEmitter {
                 .prepare(`INSERT INTO messages (id, thread_id, sender_id, subject, body, priority, in_reply_to, created_at)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
                 .run(messageId, threadId, from, subject, input.body, priority, inReplyTo, now);
+            const insertAttachment = this.db.prepare(`INSERT INTO attachments (id, message_id, position, filename, mime_type, size, data, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+            attachments.forEach((a, position) => {
+                insertAttachment.run(newId("att"), messageId, position, a.filename, a.mime_type, a.data.length, a.data, now);
+            });
             const insert = this.db.prepare(`INSERT INTO deliveries (id, message_id, agent_id, role, folder, read_at, starred, created_at)
          VALUES (?, ?, ?, ?, ?, ?, 0, ?)`);
             for (const d of deliveries) {
@@ -316,8 +338,8 @@ export class MessageStore extends EventEmitter {
           ORDER BY m.created_at DESC, m.id DESC
           LIMIT ? OFFSET ?`)
             .all(...params, limit, offset);
-        const recipients = this.recipientsFor(rows.map((r) => r.message_id));
-        return rows.map((row) => this.toSummary(row, recipients));
+        const related = this.relatedFor(rows.map((r) => r.message_id));
+        return rows.map((row) => this.toSummary(row, related));
     }
     getMessage(agentId, messageId, markRead = false) {
         const row = this.db
@@ -339,8 +361,8 @@ export class MessageStore extends EventEmitter {
                 .run(now, agentId, messageId);
             row.read_at = now;
         }
-        const recipients = this.recipientsFor([messageId]);
-        return this.toMessage(row, recipients);
+        const related = this.relatedFor([messageId]);
+        return this.toMessage(row, related);
     }
     /** Tous les messages d'un fil visibles par l'agent, du plus ancien au plus récent. */
     getThread(agentId, threadId) {
@@ -357,8 +379,20 @@ export class MessageStore extends EventEmitter {
             .all(agentId, threadId);
         if (rows.length === 0)
             throw new MessengerError(`thread not found in this mailbox: ${threadId}`, 404);
-        const recipients = this.recipientsFor(rows.map((r) => r.message_id));
-        return rows.map((row) => this.toMessage(row, recipients));
+        const related = this.relatedFor(rows.map((r) => r.message_id));
+        return rows.map((row) => this.toMessage(row, related));
+    }
+    /** Pièce jointe d'un message livré à cet agent, contenu compris. */
+    getAttachment(agentId, attachmentId) {
+        const row = this.db
+            .prepare(`SELECT a.id AS attachment_id, a.message_id, a.filename, a.mime_type, a.size, a.data
+           FROM attachments a
+          WHERE a.id = ?
+            AND EXISTS (SELECT 1 FROM deliveries d WHERE d.message_id = a.message_id AND d.agent_id = ?)`)
+            .get(attachmentId, agentId);
+        if (!row)
+            throw new MessengerError(`attachment not found in this mailbox: ${attachmentId}`, 404);
+        return row;
     }
     // --- Fils ---------------------------------------------------------------
     getThreadInfo(threadId) {
@@ -710,8 +744,8 @@ export class MessageStore extends EventEmitter {
           ORDER BY m.created_at DESC, m.id DESC
           LIMIT ? OFFSET ?`)
             .all(...params, limit, offset);
-        const recipients = this.recipientsFor(rows.map((r) => r.message_id));
-        return rows.map((row) => this.toSummary(row, recipients));
+        const related = this.relatedFor(rows.map((r) => r.message_id));
+        return rows.map((row) => this.toSummary(row, related));
     }
     /**
      * Fils du serveur entier, le plus récemment actif en tête.
@@ -806,8 +840,8 @@ export class MessageStore extends EventEmitter {
           WHERE m.thread_id = ?
           ORDER BY m.created_at ASC, m.id ASC`)
             .all(threadId);
-        const recipients = this.recipientsFor(rows.map((r) => r.message_id));
-        return rows.map((row) => ({ ...this.toSummary(row, recipients), body: row.body }));
+        const related = this.relatedFor(rows.map((r) => r.message_id));
+        return rows.map((row) => ({ ...this.toSummary(row, related), body: row.body }));
     }
     /** Message complet vu du serveur, avec l'état de lecture de chaque destinataire. */
     getMessageAdmin(messageId) {
@@ -818,12 +852,12 @@ export class MessageStore extends EventEmitter {
             .get(messageId);
         if (!row)
             throw new MessengerError(`message not found: ${messageId}`, 404);
-        const recipients = this.recipientsFor([messageId]);
+        const related = this.relatedFor([messageId]);
         const deliveries = this.db
             .prepare("SELECT agent_id, role, folder, read_at FROM deliveries WHERE message_id = ? ORDER BY role, agent_id")
             .all(messageId);
         return {
-            ...this.toMessage(row, recipients),
+            ...this.toMessage(row, related),
             deliveries: deliveries.map((d) => ({
                 agent_id: d.agent_id,
                 role: d.role,
@@ -832,6 +866,16 @@ export class MessageStore extends EventEmitter {
             })),
         };
     }
+    /** Pièce jointe vue du serveur, quelle que soit la boîte. */
+    getAttachmentAdmin(attachmentId) {
+        const row = this.db
+            .prepare(`SELECT id AS attachment_id, message_id, filename, mime_type, size, data
+           FROM attachments WHERE id = ?`)
+            .get(attachmentId);
+        if (!row)
+            throw new MessengerError(`attachment not found: ${attachmentId}`, 404);
+        return row;
+    }
     overview() {
         const messages = this.db.prepare("SELECT COUNT(*) AS n FROM messages").get().n;
         const threads = this.db.prepare("SELECT COUNT(DISTINCT thread_id) AS n FROM messages").get().n;
@@ -878,28 +922,36 @@ 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();
+    /** Destinataire et pièces jointes de chaque message demandé, par identifiant de message. */
+    relatedFor(messageIds) {
+        const related = { recipients: new Map(), attachments: new Map() };
         const ids = dedupe(messageIds);
         if (ids.length === 0)
-            return map;
+            return related;
         const placeholders = ids.map(() => "?").join(",");
-        const rows = this.db
+        const recipients = this.db
             .prepare(`SELECT message_id, agent_id FROM deliveries
           WHERE message_id IN (${placeholders}) AND role = 'to'`)
             .all(...ids);
-        for (const row of rows)
-            map.set(row.message_id, row.agent_id);
-        return map;
+        for (const row of recipients)
+            related.recipients.set(row.message_id, row.agent_id);
+        const attachments = this.db
+            .prepare(`SELECT id AS attachment_id, message_id, filename, mime_type, size FROM attachments
+          WHERE message_id IN (${placeholders})
+          ORDER BY message_id, position`)
+            .all(...ids);
+        for (const { message_id, ...info } of attachments) {
+            related.attachments.set(message_id, [...(related.attachments.get(message_id) ?? []), info]);
+        }
+        return related;
     }
-    toSummary(row, recipients) {
+    toSummary(row, related) {
         return {
             message_id: row.message_id,
             thread_id: row.thread_id,
             thread_title: row.thread_title,
             from: row.sender_id,
-            to: recipients.get(row.message_id) ?? "",
+            to: related.recipients.get(row.message_id) ?? "",
             subject: row.subject,
             preview: preview(row.body),
             priority: row.priority,
@@ -909,10 +961,11 @@ export class MessageStore extends EventEmitter {
             starred: Boolean(row.starred),
             created_at: row.created_at,
             in_reply_to: row.in_reply_to,
+            attachments: related.attachments.get(row.message_id) ?? [],
         };
     }
-    toMessage(row, recipients) {
-        const { preview: _preview, ...summary } = this.toSummary(row, recipients);
+    toMessage(row, related) {
+        const { preview: _preview, ...summary } = this.toSummary(row, related);
         return { ...summary, body: row.body };
     }
     /** Un message sans aucune livraison n'est plus lisible par personne : on le supprime. */
@@ -941,6 +994,47 @@ function normalizeLabel(value, max, field) {
         throw new MessengerError(`${field} must be at most ${max} characters`);
     return trimmed;
 }
+/**
+ * Valide les pièces jointes d'un envoi : nombre, tailles, nom et type.
+ *
+ * Le nom ne garde que sa dernière composante : il sert à nommer un fichier chez le
+ * destinataire, et ne doit jamais désigner un autre répertoire que celui qu'il choisit.
+ */
+function normalizeAttachments(attachments) {
+    if (attachments.length > MAX_ATTACHMENTS) {
+        throw new MessengerError(`at most ${MAX_ATTACHMENTS} attachments per message`);
+    }
+    let total = 0;
+    const normalized = attachments.map((attachment) => {
+        const filename = sanitizeFilename(attachment.filename);
+        if (attachment.data.length === 0)
+            throw new MessengerError(`attachment is empty: ${filename}`);
+        if (attachment.data.length > MAX_ATTACHMENT_BYTES) {
+            throw new MessengerError(`attachment exceeds ${formatBytes(MAX_ATTACHMENT_BYTES)}: ${filename}`, 413);
+        }
+        total += attachment.data.length;
+        const mimeType = (attachment.mime_type ?? "").trim().toLowerCase() || DEFAULT_MIME_TYPE;
+        if (!MIME_TYPE_RE.test(mimeType))
+            throw new MessengerError(`invalid mime_type for ${filename}: ${mimeType}`);
+        return { filename, mime_type: mimeType, data: attachment.data };
+    });
+    if (total > MAX_ATTACHMENTS_TOTAL_BYTES) {
+        throw new MessengerError(`attachments exceed ${formatBytes(MAX_ATTACHMENTS_TOTAL_BYTES)} in total`, 413);
+    }
+    return normalized;
+}
+function sanitizeFilename(value) {
+    const base = String(value ?? "")
+        .split(/[\\/]/)
+        .pop()
+        .replace(/[\u0000-\u001f\u007f<>:"|?*]/g, "_")
+        .trim();
+    if (!base || base === "." || base === "..")
+        throw new MessengerError("attachment filename cannot be empty");
+    if (base.length > FILENAME_MAX)
+        throw new MessengerError(`attachment filename must be at most ${FILENAME_MAX} characters`);
+    return base;
+}
 function dedupe(values) {
     return [...new Set(values)];
 }

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

@@ -35,6 +35,21 @@ export interface AgentDirectoryEntry extends Agent {
     /** Plus récent de la dernière connexion et de la dernière livraison ; null si aucune. */
     last_activity_at: string | null;
 }
+/** Pièce jointe telle qu'elle voyage avec un message : ses métadonnées, sans son contenu. */
+export interface AttachmentInfo {
+    attachment_id: string;
+    filename: string;
+    mime_type: string;
+    /** Taille en octets. */
+    size: number;
+}
+/** Pièce jointe fournie à l'envoi. */
+export interface AttachmentUpload {
+    filename: string;
+    /** Type MIME ; `application/octet-stream` s'il est absent. */
+    mime_type?: string | null;
+    data: Buffer;
+}
 export interface SendMessageInput {
     from: string;
     /** Un échange lie exactement deux boîtes : un seul destinataire par message. */
@@ -47,6 +62,7 @@ export interface SendMessageInput {
     /** Nom lisible donné au fil. Sur une réponse, renomme le fil existant. */
     thread_title?: string | null;
     thread_description?: string | null;
+    attachments?: AttachmentUpload[];
 }
 /**
  * Intitulé d'un fil de discussion.
@@ -98,6 +114,7 @@ export interface MessageSummary {
     starred: boolean;
     created_at: string;
     in_reply_to: string | null;
+    attachments: AttachmentInfo[];
 }
 export interface Message extends Omit<MessageSummary, "preview"> {
     body: string;

package/dist/src/mcp/start.js

@@ -39,7 +39,8 @@ Resuming earlier work:
 Writing:
 - One message goes to exactly one mailbox, and never to your own. To reach several correspondents, 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.`;
+- Call \`enable_notifications\` once at the start of the session and arm the watcher it hands you. Until then, no incoming message reaches you.
+- The host stops that watcher after 30 minutes at most. Each time it tells you the watcher expired, re-arm it at once with the same Monitor call; otherwise notifications stop for good.`;
 /** 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: {} }, instructions: INSTRUCTIONS });

package/dist/src/mcp/tools.js

@@ -1,10 +1,45 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { z } from "zod";
 import { writeHandoff } from "../cli/watch-handoff.js";
+import { MAX_ATTACHMENTS, MAX_ATTACHMENTS_TOTAL_BYTES, MAX_ATTACHMENT_BYTES, formatBytes } from "../core/attachments.js";
 import { PRIORITIES, SYSTEM_FOLDERS } from "../core/types.js";
 import { rebind } from "./mailbox-registry.js";
 import { forgetCandidate, getResumeState } from "./resume-state.js";
 /** Nom publié : l'agent recopie la commande, il n'a pas à connaître de chemin local. */
 const PACKAGE_NAME = "@imenam/mcp-messenger";
+/** Durée maximale d'un `Monitor` côté hôte : au-delà, l'hôte la ramène à cette valeur. */
+const MONITOR_TIMEOUT_MS = 1_800_000;
+/** Répertoire où `save_attachment` écrit quand l'agent ne donne pas de destination. */
+const DEFAULT_ATTACHMENT_DIR = path.join(os.tmpdir(), "mcp-messenger", "attachments");
+/** Type MIME déduit de l'extension, pour les formats courants. */
+const MIME_TYPES = {
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".yaml": "application/yaml",
+    ".yml": "application/yaml",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "text/javascript",
+    ".log": "text/plain",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".tar": "application/x-tar",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
 const FOLDER_HINT = `Folder name. System folders: ${SYSTEM_FOLDERS.join(", ")}. Custom folders come from list_folders.`;
 export const TOOLS = [
     {
@@ -105,6 +140,23 @@ export const TOOLS = [
                     description: "Plain-language name of the conversation, e.g. 'Résolution de l'échec du test de parsing'. Name the thread when you open it — you already know what it is about. On a reply it renames the thread for everyone (same effect as rename_thread).",
                 },
                 thread_description: { type: "string", description: "Optional longer description of the thread." },
+                attachments: {
+                    type: "array",
+                    maxItems: MAX_ATTACHMENTS,
+                    description: `Files to attach, read from this machine's disk. At most ${MAX_ATTACHMENTS} files, ${formatBytes(MAX_ATTACHMENT_BYTES)} each and ${formatBytes(MAX_ATTACHMENTS_TOTAL_BYTES)} in total. The recipient saves them with save_attachment.`,
+                    items: {
+                        type: "object",
+                        properties: {
+                            path: {
+                                type: "string",
+                                description: "Path of the file to attach. Prefer an absolute path; a relative one is resolved against this MCP server's working directory.",
+                            },
+                            name: { type: "string", description: "File name shown to the recipient. Defaults to the file's own name." },
+                        },
+                        required: ["path"],
+                        additionalProperties: false,
+                    },
+                },
             },
             required: ["to", "subject", "body"],
             additionalProperties: false,
@@ -150,6 +202,23 @@ export const TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "save_attachment",
+        description: "Save a file attached to a message of this mailbox onto this machine's disk, and return the path it was written to. Attachment ids are listed under the message by read_message and get_thread. Read the saved file with your usual file tools.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                attachment_id: { type: "string", description: "Attachment id (att_…) shown under the message." },
+                path: {
+                    type: "string",
+                    description: "Where to save it: an existing directory (the file keeps its name) or a file path. Defaults to a directory under the system temp folder.",
+                },
+                overwrite: { type: "boolean", description: "Replace an existing file at that path. Defaults to false." },
+            },
+            required: ["attachment_id"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "mark_messages",
         description: "Mark messages as read or unread, and/or star or unstar them.",
@@ -217,7 +286,7 @@ export const TOOLS = [
     },
     {
         name: "enable_notifications",
-        description: "Get notified of incoming messages without waiting for them. Returns immediately: it blocks nothing and starts nothing on its own. It hands you the exact Monitor call to make right after — arming that watcher is what actually delivers notifications, and until you do it no message will reach you. Call this once at the start of a session, before any other work; then just keep working, incoming messages will interrupt you on their own.",
+        description: "Get notified of incoming messages without waiting for them. Returns immediately: it blocks nothing and starts nothing on its own. It hands you the exact Monitor call to make right after — arming that watcher is what actually delivers notifications, and until you do it no message will reach you. Call this once at the start of a session, before any other work; then just keep working, incoming messages will interrupt you on their own. The host stops the watcher after 30 minutes at most: re-arm it with the same Monitor call each time it expires.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
@@ -242,6 +311,15 @@ const schemas = {
         reply_to: z.string().optional(),
         thread_name: z.string().trim().min(1).max(200).optional(),
         thread_description: z.string().trim().min(1).max(2000).optional(),
+        attachments: z
+            .array(z.object({ path: z.string().trim().min(1), name: z.string().trim().min(1).max(255).optional() }))
+            .max(MAX_ATTACHMENTS)
+            .optional(),
+    }),
+    save_attachment: z.object({
+        attachment_id: z.string().trim().min(1),
+        path: z.string().trim().min(1).optional(),
+        overwrite: z.boolean().optional(),
     }),
     list_messages: z.object({
         folder: z.string().optional(),
@@ -423,6 +501,7 @@ export async function callTool(client, name, rawArgs) {
         }
         case "send_message": {
             const input = schemas.send_message.parse(args);
+            const attachments = await readAttachments(input.attachments ?? []);
             const result = await client.sendMessage({
                 to: input.to,
                 subject: input.subject,
@@ -432,12 +511,16 @@ export async function callTool(client, name, rawArgs) {
                 // Le protocole HTTP et le stockage gardent `thread_title` ; seul l'outil dit `thread_name`.
                 thread_title: input.thread_name ?? null,
                 thread_description: input.thread_description ?? null,
+                attachments,
             });
             const lines = [
                 `Message sent: ${result.message_id}`,
                 `Thread: ${formatThreadRef(result.thread_title, result.thread_id)}`,
                 `Delivered to: ${result.delivered_to}`,
             ];
+            if (attachments.length > 0) {
+                lines.push(`Attachments: ${attachments.map((a) => a.filename).join(", ")}`);
+            }
             if (!result.thread_title && !input.reply_to) {
                 lines.push("This thread has no name yet — rename_thread with its thread_id makes it readable for everyone.");
             }
@@ -470,6 +553,22 @@ export async function callTool(client, name, rawArgs) {
                 .join("\n");
             return [header, "", ...messages.map(formatMessage)].join("\n\n---\n\n");
         }
+        case "save_attachment": {
+            const input = schemas.save_attachment.parse(args);
+            const attachment = await client.downloadAttachment(input.attachment_id);
+            const target = await attachmentTarget(input.path, input.attachment_id, attachment.filename);
+            await mkdir(path.dirname(target), { recursive: true });
+            try {
+                await writeFile(target, attachment.data, { flag: input.overwrite ? "w" : "wx" });
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    throw new Error(`a file already exists at ${target} — pass overwrite: true or choose another path`);
+                }
+                throw error;
+            }
+            return `Saved ${attachment.filename} (${attachment.mime_type}, ${formatBytes(attachment.data.length)}) to ${target}`;
+        }
         case "mark_messages": {
             const input = schemas.mark_messages.parse(args);
             if (input.read === undefined && input.starred === undefined) {
@@ -522,6 +621,9 @@ export async function callTool(client, name, rawArgs) {
                     `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.",
+                    "Only exception: if the host just told you your watcher expired or stopped, re-arm it",
+                    `with the same Monitor call (command \`npx -y ${PACKAGE_NAME} --watch ${mailbox}\`,`,
+                    `timeout_ms ${MONITOR_TIMEOUT_MS}).`,
                 ].join("\n");
             }
             const lines = [
@@ -530,11 +632,15 @@ export async function callTool(client, name, rawArgs) {
                 "Last step — call the Monitor tool now, with exactly these arguments:",
                 `  command:     npx -y ${PACKAGE_NAME} --watch ${mailbox}`,
                 "  description: Incoming messenger messages",
-                "  persistent:  true",
+                `  timeout_ms:  ${MONITOR_TIMEOUT_MS}`,
                 "",
                 "Until that watcher is armed, nothing will reach you: no message will be announced.",
                 "Once it is, keep working normally — each incoming message shows up on its own, even",
                 "while you are idle. One line per message; read it with read_message.",
+                "",
+                "The host stops every monitor after 30 minutes at most. Each time it tells you this",
+                "watcher expired, call Monitor again right away with the same arguments — do not call",
+                "enable_notifications again. Skip that and notifications stop for good.",
             ];
             if (client.isAttachedElsewhere) {
                 lines.push("", `Note: you are attached to \`${mailbox}\`, not to this session's own mailbox ` +
@@ -558,6 +664,42 @@ export async function callTool(client, name, rawArgs) {
             throw new Error(`Unknown tool: ${name}`);
     }
 }
+/** Lit sur le disque local les fichiers à joindre, en refusant d'emblée ceux qui dépassent les limites. */
+async function readAttachments(entries) {
+    let total = 0;
+    const attachments = [];
+    for (const entry of entries) {
+        const file = path.resolve(entry.path);
+        const info = await stat(file).catch(() => null);
+        if (!info?.isFile())
+            throw new Error(`attachment is not a readable file: ${file}`);
+        if (info.size > MAX_ATTACHMENT_BYTES) {
+            throw new Error(`attachment exceeds ${formatBytes(MAX_ATTACHMENT_BYTES)}: ${file} (${formatBytes(info.size)})`);
+        }
+        total += info.size;
+        if (total > MAX_ATTACHMENTS_TOTAL_BYTES) {
+            throw new Error(`attachments exceed ${formatBytes(MAX_ATTACHMENTS_TOTAL_BYTES)} in total`);
+        }
+        const filename = entry.name ?? path.basename(file);
+        attachments.push({
+            filename,
+            mime_type: MIME_TYPES[path.extname(filename).toLowerCase()] ?? null,
+            content_base64: (await readFile(file)).toString("base64"),
+        });
+    }
+    return attachments;
+}
+/**
+ * Chemin d'écriture d'une pièce jointe : dans le répertoire donné sous son propre nom, au
+ * chemin donné s'il désigne un fichier, ou dans un répertoire temporaire propre à la pièce.
+ */
+async function attachmentTarget(requested, attachmentId, filename) {
+    if (!requested)
+        return path.join(DEFAULT_ATTACHMENT_DIR, attachmentId, filename);
+    const resolved = path.resolve(requested);
+    const isDirectory = /[\\/]$/.test(requested) || (await stat(resolved).catch(() => null))?.isDirectory();
+    return isDirectory ? path.join(resolved, filename) : resolved;
+}
 async function renameMailbox(client, name, description) {
     const agent = await client.updateProfile({ display_name: name, description });
     return [
@@ -743,7 +885,7 @@ function formatSummary(message) {
         `${flags} ${message.subject}${priority}`,
         `   from ${message.from} to ${message.to || "—"} · ${message.created_at}`,
         `   ${message.preview}`,
-        `   id ${message.message_id} · thread ${formatThreadRef(message.thread_title, message.thread_id)}`,
+        `   id ${message.message_id} · thread ${formatThreadRef(message.thread_title, message.thread_id)}${message.attachments.length > 0 ? ` · ${message.attachments.length} attachment(s)` : ""}`,
     ].join("\n");
 }
 function formatMessage(message) {
@@ -758,5 +900,11 @@ function formatMessage(message) {
     ]
         .filter(Boolean)
         .join("\n");
-    return `${header}\n\n${message.body}`;
+    const attachments = message.attachments.length > 0
+        ? `\n\nAttachments (save with save_attachment):\n${message.attachments.map(formatAttachment).join("\n")}`
+        : "";
+    return `${header}\n\n${message.body}${attachments}`;
+}
+function formatAttachment(attachment) {
+    return `  ${attachment.attachment_id} · ${attachment.filename} (${attachment.mime_type}, ${formatBytes(attachment.size)})`;
 }

package/dist/src/server/app.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { timingSafeEqual } from "node:crypto";
 import { rateLimit } from "express-rate-limit";
 import { z } from "zod";
+import { MAX_ATTACHMENTS, MAX_ATTACHMENTS_TOTAL_BYTES, contentDisposition } from "../core/attachments.js";
 import { MessengerError, normalizeAgentId } from "../core/store.js";
 import { PRIORITIES } from "../core/types.js";
 import { WatcherRegistry } from "./watchers.js";
@@ -12,6 +13,9 @@ import { CONSOLE_COOKIE, ConsoleSessions, consoleSessionId } from "./console-ses
 import { APP_VERSION } from "../version.js";
 import { logger } from "../logger.js";
 const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "ui");
+const JSON_TYPES = ["application/json", "application/*+json"];
+/** Corps d'un envoi : le texte, plus les pièces jointes encodées en base64 (4 octets pour 3). */
+const SEND_BODY_LIMIT = Math.ceil((MAX_ATTACHMENTS_TOTAL_BYTES * 4) / 3) + 1024 * 1024;
 const agentIdSchema = z.string().trim().min(1).max(128);
 const idListSchema = z.array(z.string().trim().min(1)).min(1).max(200);
 /** Nom et description de la boîte : ce que l'agent pose lui-même sur sa session. */
@@ -34,6 +38,14 @@ const sendSchema = z.object({
     reply_to: z.string().trim().min(1).nullish(),
     thread_title: z.string().trim().min(1).max(200).nullish(),
     thread_description: z.string().trim().min(1).max(2000).nullish(),
+    attachments: z
+        .array(z.object({
+        filename: z.string().trim().min(1).max(255),
+        mime_type: z.string().trim().max(255).nullish(),
+        content_base64: z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/, "expected base64 content"),
+    }))
+        .max(MAX_ATTACHMENTS)
+        .optional(),
 });
 const threadLabelSchema = z
     .object({
@@ -151,7 +163,10 @@ export function createApp({ store, config }) {
         },
         crossOriginEmbedderPolicy: false,
     }));
-    app.use(express.json({ type: ["application/json", "application/*+json"], limit: "2mb" }));
+    // L'envoi d'un message a sa propre limite, plus large pour ses pièces jointes, et ne
+    // s'applique qu'une fois l'agent authentifié.
+    const jsonBody = express.json({ type: JSON_TYPES, limit: "2mb" });
+    app.use((req, res, next) => (isSendRequest(req) ? next() : jsonBody(req, res, next)));
     app.use(rateLimit({
         windowMs: config.rateLimit.windowMs,
         limit: config.rateLimit.max,
@@ -209,6 +224,9 @@ export function createApp({ store, config }) {
     admin.get("/messages/:id", (req, res) => {
         res.json(store.getMessageAdmin(String(req.params.id)));
     });
+    admin.get("/attachments/:id", (req, res) => {
+        sendAttachment(res, store.getAttachmentAdmin(String(req.params.id)));
+    });
     // Déclarée avant `/threads/:id` : la console lit d'abord les fils, le détail ensuite.
     admin.get("/threads", (req, res) => {
         const query = adminThreadsSchema.parse(req.query);
@@ -373,7 +391,7 @@ export function createApp({ store, config }) {
     api.get("/mailbox", (req, res) => {
         res.json({ ...store.stats(req.agentId), watcher: watchers.status(req.agentId) });
     });
-    api.post("/messages", (req, res) => {
+    api.post("/messages", express.json({ type: JSON_TYPES, limit: SEND_BODY_LIMIT }), (req, res) => {
         const input = sendSchema.parse(req.body ?? {});
         const result = store.sendMessage({
             from: req.agentId,
@@ -384,6 +402,11 @@ export function createApp({ store, config }) {
             reply_to: input.reply_to ?? null,
             thread_title: input.thread_title ?? null,
             thread_description: input.thread_description ?? null,
+            attachments: (input.attachments ?? []).map((a) => ({
+                filename: a.filename,
+                mime_type: a.mime_type ?? null,
+                data: Buffer.from(a.content_base64, "base64"),
+            })),
         });
         logger.info(`message ${result.message_id}: ${req.agentId} -> ${result.delivered_to}`);
         res.status(201).json(result);
@@ -409,6 +432,9 @@ export function createApp({ store, config }) {
         const markRead = req.query.mark_read !== "false";
         res.json(store.getMessage(req.agentId, String(req.params.id), markRead));
     });
+    api.get("/attachments/:id", (req, res) => {
+        sendAttachment(res, store.getAttachment(req.agentId, String(req.params.id)));
+    });
     api.get("/threads", (req, res) => {
         const query = listThreadsQuerySchema.parse(req.query);
         res.json({ threads: store.listThreads(req.agentId, query) });
@@ -485,12 +511,32 @@ export function createApp({ store, config }) {
             res.status(400).json({ error: "invalid request", details: z.treeifyError(err) });
             return;
         }
+        // Erreurs du lecteur de corps (trop gros, JSON illisible) : leur message est fait pour être lu.
+        if (isExposedHttpError(err)) {
+            res.status(err.status).json({ error: err.message });
+            return;
+        }
         logger.error("unhandled error", err);
         // Le détail reste dans les logs : la réponse ne doit rien révéler de l'hôte.
         res.status(500).json({ error: "internal server error" });
     });
     return app;
 }
+function isExposedHttpError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const { expose, status } = err;
+    return expose === true && typeof status === "number" && status >= 400 && status < 500;
+}
+function isSendRequest(req) {
+    return req.method === "POST" && req.path === "/api/messages";
+}
+function sendAttachment(res, attachment) {
+    res.setHeader("content-type", attachment.mime_type);
+    res.setHeader("content-length", String(attachment.data.length));
+    res.setHeader("content-disposition", contentDisposition(attachment.filename));
+    res.end(attachment.data);
+}
 /**
  * Exige un jeton connu du serveur sur toute requête entrante.
  *

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

@@ -27,6 +27,7 @@ const ICONS = {
   link: ["M10 13a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1", "M14 11a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1"],
   chevron: ["m9 18 6-6-6-6"],
   info: ["M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18z", "M12 11v5", "M12 8h.01"],
+  paperclip: ["m21 11-8.5 8.5a5 5 0 0 1-7-7L14 4a3.5 3.5 0 0 1 5 5l-8.5 8.5a2 2 0 0 1-3-3L15 7"],
   trash: ["M3 6h18", "M8 6V4a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v2", "M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"],
 };
 
@@ -961,6 +962,9 @@ function fillMessage(item, message, isLast) {
   column.appendChild(content);
 
   content.appendChild(messageText(message));
+  if (message.attachments && message.attachments.length > 0) {
+    content.appendChild(attachmentList(message.attachments));
+  }
 
   const foot = node("div", "message-foot");
   foot.appendChild(
@@ -986,6 +990,30 @@ function messageText(message) {
   return container;
 }
 
+/** Pièces jointes d'un message : un lien de téléchargement par fichier. */
+function attachmentList(attachments) {
+  const list = node("ul", "attachments");
+  for (const attachment of attachments) {
+    const item = node("li");
+    const link = node("a", "attachment");
+    link.href = `/admin/attachments/${encodeURIComponent(attachment.attachment_id)}`;
+    link.download = attachment.filename;
+    link.title = attachment.mime_type;
+    link.appendChild(icon("paperclip"));
+    link.appendChild(node("span", "attachment-name", attachment.filename));
+    link.appendChild(node("span", "attachment-size", formatSize(attachment.size)));
+    item.appendChild(link);
+    list.appendChild(item);
+  }
+  return list;
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} o`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} Ko`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} Mo`;
+}
+
 // --- Détails d'un message --------------------------------------------------
 
 /**

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

@@ -1627,6 +1627,50 @@ body {
   font-weight: 600;
 }
 
+.attachments {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin: 10px 0 0;
+  padding: 0;
+  list-style: none;
+}
+
+.attachment {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  max-width: 100%;
+  padding: 4px 10px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--panel);
+  color: var(--text);
+  font-size: 12px;
+  text-decoration: none;
+}
+
+.attachment:hover {
+  background: var(--accent-soft);
+  border-color: var(--accent-softer);
+}
+
+.attachment .icon {
+  flex: none;
+  color: var(--muted);
+}
+
+.attachment-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.attachment-size {
+  flex: none;
+  color: var(--muted);
+}
+
 .message-foot {
   display: flex;
   align-items: center;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.28";
+export declare const APP_VERSION = "1.0.30";

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.28";
+export const APP_VERSION = "1.0.30";

package/package.json

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