@imenam/mcp-messenger 1.0.30 → 1.0.31

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

@@ -35,6 +35,30 @@ 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;
 }
+/** Une des deux boîtes d'une liaison, et le moment où son agent en a pris connaissance. */
+export interface LinkEnd {
+    mailbox: string;
+    /** null tant que l'agent de cette boîte n'a pas lu la liaison (`whoami`, `list_links`, `list_agents`). */
+    seen_at: string | null;
+}
+/**
+ * Liaison posée depuis la console entre deux boîtes : chacune connaît l'autre comme
+ * correspondante désignée, sans que les agents aient à échanger d'adresse.
+ */
+export interface MailboxLink {
+    link_id: string;
+    /** Motif transmis aux deux agents. */
+    note: string | null;
+    created_at: string;
+    mailboxes: [LinkEnd, LinkEnd];
+}
+/** Liaison vue depuis l'une de ses deux boîtes : la fiche de la boîte d'en face. */
+export interface LinkedMailbox {
+    link_id: string;
+    note: string | null;
+    created_at: string;
+    correspondent: Agent;
+}
 /** Pièce jointe telle qu'elle voyage avec un message : ses métadonnées, sans son contenu. */
 export interface AttachmentInfo {
     attachment_id: string;

package/dist/src/mcp/start.js

@@ -18,28 +18,31 @@ import { TOOLS, callTool } from "./tools.js";
  * recopier une adresse dans le corps d'un message (le serveur la pose déjà, la copie ment
  * dès qu'elle vieillit). Les dire ici, c'est les dire avant l'erreur.
  */
-const INSTRUCTIONS = `mcp-messenger gives this session a mailbox and lets it exchange messages with other agent sessions.
-
-Two words, two different things, used consistently by every tool here:
-- a **mailbox** is an address (\`box_…\`). It identifies exactly one session, and it is what you write to.
-- an **agent name** is the project a session works for. It is a label, never an address, and every session of that project carries it.
-
-Who you are, and who the others are — read this before writing to anyone:
-- A session is identified by its mailbox address, and by nothing else. \`whoami\` gives you yours.
-- The agent name (e.g. "Ai Corrector Dev") comes from the configuration and says which project the agent works on. It is NOT unique: every session started from that configuration carries it.
-- \`list_agents\` groups mailboxes under their agent name: one group per project, one line per session. A group holding several lines is several live sessions of that project, each with its own address — pick one of those addresses, never the group name.
-- One of those groups may carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — those are other sessions of the same project, each a different agent with its own mailbox. Compare addresses, never names.
-- Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
-
-Resuming earlier work:
-- A resumed session usually keeps the mailbox it had: the address, the threads and the unread messages come back on their own. \`whoami\` says so when it happens.
-- When it cannot be decided automatically, \`whoami\` lists the mailboxes left by a stopped session of this project. If you are continuing that work, call \`attach_to_mailbox\` with the right address.
-- If a \`box_…\` address appears earlier in your own context, from a previous part of this conversation, that is your mailbox from before: attach to it rather than writing from a fresh one, so your correspondents keep reaching you at the address they know.
-
-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.
+const INSTRUCTIONS = `mcp-messenger gives this session a mailbox and lets it exchange messages with other agent sessions.
+
+Two words, two different things, used consistently by every tool here:
+- a **mailbox** is an address (\`box_…\`). It identifies exactly one session, and it is what you write to.
+- an **agent name** is the project a session works for. It is a label, never an address, and every session of that project carries it.
+
+Who you are, and who the others are — read this before writing to anyone:
+- A session is identified by its mailbox address, and by nothing else. \`whoami\` gives you yours.
+- The agent name (e.g. "Ai Corrector Dev") comes from the configuration and says which project the agent works on. It is NOT unique: every session started from that configuration carries it.
+- \`list_agents\` groups mailboxes under their agent name: one group per project, one line per session. A group holding several lines is several live sessions of that project, each with its own address — pick one of those addresses, never the group name.
+- One of those groups may carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — those are other sessions of the same project, each a different agent with its own mailbox. Compare addresses, never names.
+- Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
+
+Resuming earlier work:
+- A resumed session usually keeps the mailbox it had: the address, the threads and the unread messages come back on their own. \`whoami\` says so when it happens.
+- When it cannot be decided automatically, \`whoami\` lists the mailboxes left by a stopped session of this project. If you are continuing that work, call \`attach_to_mailbox\` with the right address.
+- If a \`box_…\` address appears earlier in your own context, from a previous part of this conversation, that is your mailbox from before: attach to it rather than writing from a fresh one, so your correspondents keep reaching you at the address they know.
+
+Linked mailboxes:
+- The user can link this mailbox to others from the web console: those are the correspondents you are meant to work with. \`whoami\` and \`list_links\` list them, and the notification watcher announces each new link as it arrives.
+
+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.
 - 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) {

package/dist/src/mcp/tools.js

@@ -107,6 +107,11 @@ export const TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "list_links",
+        description: "List the mailboxes the user has linked to this one from the web console, newest first: these are the correspondents you are meant to work with, with the reason the user gave. Write to them with send_message, using the address listed here. Links arrive while you work — the notification watcher announces each new one — and whoami lists them too.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
     {
         name: "list_agents",
         description: "List the mailboxes known to the server, grouped by agent name — one group per project, one line per session mailbox inside it, most recently active first. An agent name is shared by every session of the same project, so a group with several lines means several live sessions, each with its own mailbox address. Your own mailbox is never listed — you cannot write to yourself. Use it to find the mailbox address you want to write to; pass agent_name to expand a group whose sessions were not all listed.",
@@ -396,6 +401,7 @@ export async function callTool(client, name, rawArgs) {
             const health = await client.health().catch(() => null);
             const folders = stats.folders.map((f) => `  ${f.name.padEnd(12)} ${f.total} message(s), ${f.unread} unread`);
             const self = await client.getAgent(client.agentId).catch(() => null);
+            const links = await client.listLinks();
             const lines = [
                 `Mailbox address: ${client.agentId}`,
                 // Personne n'a besoin qu'on la lui envoie : l'annuaire la donne, et chaque message
@@ -411,6 +417,7 @@ export async function callTool(client, name, rawArgs) {
                 self?.display_name
                     ? `Mailbox name: ${self.display_name}`
                     : "Mailbox name: none — call rename_mailbox so the user can tell this session apart from the others.",
+                ...linkLines(links),
             ];
             if (client.isAttachedElsewhere) {
                 lines.push(`Attached to another mailbox. This session's own mailbox is ${client.sessionAgentId}.`);
@@ -491,13 +498,27 @@ export async function callTool(client, name, rawArgs) {
                 return `No thread in this mailbox${scope} matching these filters.`;
             return [`${threads.length} thread(s)${scope}:`, "", ...threads.map(formatThread)].join("\n");
         }
+        case "list_links": {
+            const links = await client.listLinks();
+            if (links.length === 0) {
+                return "No mailbox is linked to this one yet. The user links mailboxes from the web console; the notification watcher announces each new link.";
+            }
+            return [
+                `${links.length} mailbox(es) linked to this one by the user, newest first:`,
+                "",
+                ...links.map(formatLink),
+                "",
+                "Write to them with send_message, using the address shown. Do not repeat the address in the message body.",
+            ].join("\n");
+        }
         case "list_agents": {
             const input = schemas.list_agents.parse(args);
             const agents = await client.listAgents();
             if (agents.length === 0)
                 return "No other mailbox on this server yet.";
+            const linked = new Set((await client.listLinks()).map((link) => link.correspondent.id));
             const groups = groupByAgentName(agents);
-            return input.agent_name ? formatAgentGroup(groups, input.agent_name) : formatDirectory(groups);
+            return input.agent_name ? formatAgentGroup(groups, input.agent_name, linked) : formatDirectory(groups, linked);
         }
         case "send_message": {
             const input = schemas.send_message.parse(args);
@@ -744,9 +765,9 @@ function groupByAgentName(agents) {
     return [...groups.values()];
 }
 /** `boîte — nom · activité` : une ligne par session, l'adresse en tête car c'est elle qu'on copie. */
-function formatMailboxLine(agent) {
+function formatMailboxLine(agent, linked) {
     const seen = agent.last_activity_at ? `last active ${agent.last_activity_at}` : "never active";
-    const flags = agent.registered ? "" : " · never connected";
+    const flags = `${agent.registered ? "" : " · never connected"}${linked.has(agent.id) ? " · linked to you" : ""}`;
     return `  • ${agent.id} — ${agent.display_name ?? "no mailbox name"} · ${seen}${flags}`;
 }
 /**
@@ -763,7 +784,7 @@ const DIRECTORY_FOOTER = [
     "is never listed here. Always write to a mailbox address taken from this list, never to a name.",
     "To see what you have already exchanged with one of them, call list_threads with its address in with_mailbox.",
 ];
-function formatDirectory(groups) {
+function formatDirectory(groups, linked) {
     const mailboxes = groups.reduce((total, group) => total + group.mailboxes.length, 0);
     const blocks = groups.map((group) => {
         const sessions = group.mailboxes.length;
@@ -773,7 +794,7 @@ function formatDirectory(groups) {
         // Un agent à sessions nombreuses ne doit pas noyer les autres : les plus récentes
         // suffisent à écrire, `agent_name` donne le reste à qui en a besoin.
         const shown = sessions > SESSIONS_SHOWN_PER_AGENT ? group.mailboxes.slice(0, 3) : group.mailboxes;
-        lines.push(...shown.map(formatMailboxLine));
+        lines.push(...shown.map((agent) => formatMailboxLine(agent, linked)));
         if (shown.length < sessions) {
             lines.push(`  … ${sessions - shown.length} more session(s) — list_agents with agent_name: "${group.name}" lists them all.`);
         }
@@ -789,7 +810,7 @@ function formatDirectory(groups) {
     ].join("\n");
 }
 /** Toutes les sessions d'un agent, décrites une par une : le second niveau de l'annuaire. */
-function formatAgentGroup(groups, requested) {
+function formatAgentGroup(groups, requested, linked) {
     const wanted = requested.trim().toLowerCase();
     const group = groups.find((g) => g.name.toLowerCase() === wanted);
     if (!group) {
@@ -802,7 +823,7 @@ function formatAgentGroup(groups, requested) {
             `• ${agent.id}`,
             `  Mailbox: ${agent.display_name ?? "not named — this session never said what it works on"}`,
             agent.description ? `  ${agent.description}` : null,
-            `  ${seen}${agent.registered ? "" : " · never connected"}`,
+            `  ${seen}${agent.registered ? "" : " · never connected"}${linked.has(agent.id) ? " · linked to you" : ""}`,
         ]
             .filter(Boolean)
             .join("\n");
@@ -862,6 +883,23 @@ function resumeLines(client) {
     }
     return lines;
 }
+/** Ce que `whoami` dit des liaisons posées par l'utilisateur sur cette boîte. */
+function linkLines(links) {
+    if (links.length === 0) {
+        return ["Linked mailboxes: none yet — the user links mailboxes from the web console."];
+    }
+    return [
+        "Linked mailboxes — correspondents the user designated for this session:",
+        ...links.map((link) => `  ${formatLink(link)}`),
+        "  ↳ write to them with send_message; list_links details them.",
+    ];
+}
+/** `• adresse — Agent · Boîte · liée le … — motif` */
+function formatLink(link) {
+    const names = formatAgentNames(link.correspondent) || "unnamed mailbox";
+    const note = link.note ? ` — ${link.note}` : "";
+    return `• ${link.correspondent.id} — ${names} · linked ${link.created_at}${note}`;
+}
 /** `titre (id)`, ou l'id seul tant que le fil n'a pas été nommé. */
 function formatThreadRef(title, threadId) {
     return title ? `${title} (${threadId})` : threadId;

package/dist/src/server/app.js

@@ -133,6 +133,10 @@ const purgeSchema = z
     .refine((input) => [input.before, input.created_before, input.empty].filter((value) => value !== undefined).length === 1, {
     message: "provide exactly one of `before` (inactive since that date), `created_before` (created before that date) or `empty: true`",
 });
+const linkSchema = z.object({
+    mailboxes: z.tuple([agentIdSchema, agentIdSchema]),
+    note: z.string().trim().max(500).nullish(),
+});
 const adminListSchema = z.object({
     search: z.string().trim().min(1).optional(),
     agent: z.string().trim().min(1).optional(),
@@ -209,7 +213,7 @@ export function createApp({ store, config }) {
     app.get("/", (_req, res) => {
         res.redirect("/ui/");
     });
-    // --- Supervision (lecture, sauf les nettoyages de boîtes) ----------------
+    // --- Supervision (lecture, liaisons et nettoyages de boîtes) -------------
     // Montée avant la porte d'entrée : son contrôle est au moins aussi strict (session de
     // console ou jeton admin), et la session par cookie n'est reconnue nulle part ailleurs.
     const admin = express.Router();
@@ -281,7 +285,7 @@ export function createApp({ store, config }) {
         res.json({ mailboxes: store.emptyMailboxes() });
     });
     /**
-     * La seule route de la console qui écrit, et elle détruit.
+     * Suppression en lot : elle détruit.
      *
      * Deux garde-fous, parce qu'un nettoyage ne se rattrape pas : le critère est redemandé
      * avec les adresses, et le serveur refuse toute adresse qui n'y répond plus au moment
@@ -331,6 +335,21 @@ export function createApp({ store, config }) {
         logger.warn(`admin delete: mailbox ${id} deleted (${removed.messages} message(s) erased)`);
         res.json({ mailbox: id, ...removed });
     });
+    admin.get("/links", (_req, res) => {
+        res.json({ links: store.listLinks() });
+    });
+    admin.post("/links", (req, res) => {
+        const input = linkSchema.parse(req.body ?? {});
+        const link = store.createLink(input.mailboxes[0], input.mailboxes[1], input.note ?? null);
+        logger.info(`admin link ${link.link_id}: ${link.mailboxes[0].mailbox} <-> ${link.mailboxes[1].mailbox}`);
+        res.status(201).json({ link });
+    });
+    admin.delete("/links/:id", (req, res) => {
+        const linkId = String(req.params.id);
+        store.deleteLink(linkId);
+        logger.info(`admin unlink ${linkId}`);
+        res.json({ link_id: linkId });
+    });
     app.use("/admin", admin);
     // Porte d'entrée de tout le reste : aucune requête n'est servie sans jeton valide. Le
     // contrôle par route (identité de l'agent) vient ensuite.
@@ -388,6 +407,10 @@ export function createApp({ store, config }) {
             throw new MessengerError(`mailbox not found: ${req.params.id}`, 404);
         res.json({ agent });
     });
+    // Lire ses liaisons, c'est en prendre connaissance : la console l'affiche comme reçue.
+    api.get("/links", (req, res) => {
+        res.json({ links: store.linksFor(req.agentId, { markSeen: true }) });
+    });
     api.get("/mailbox", (req, res) => {
         res.json({ ...store.stats(req.agentId), watcher: watchers.status(req.agentId) });
     });
@@ -460,7 +483,8 @@ export function createApp({ store, config }) {
     });
     // Attente longue : seuls les messages arrivés APRÈS le début de l'attente réveillent
     // l'appelant ; les non-lus déjà présents sont ignorés (sinon l'outil rendrait la main
-    // immédiatement tant que la boîte n'est pas vidée).
+    // immédiatement tant que la boîte n'est pas vidée). Un veilleur est aussi réveillé par
+    // une liaison posée sur sa boîte.
     api.get("/wait", (req, res) => {
         const { timeout_seconds, folder, watcher } = waitQuerySchema.parse(req.query);
         const agentId = req.agentId;
@@ -471,11 +495,15 @@ export function createApp({ store, config }) {
         // Le relâchement doit couvrir les trois sorties possibles : message, expiration,
         // client parti. Un compteur qui ne redescend pas ferait croire à un veilleur éternel.
         const releaseWatcher = watcher ? watchers.begin(agentId) : () => { };
-        const done = (payload) => {
+        const stop = () => {
             clearTimeout(timer);
             store.off("message", onMessage);
-            req.off("close", onClose);
+            store.off("link", onLink);
+            req.off("close", stop);
             releaseWatcher();
+        };
+        const done = (payload) => {
+            stop();
             if (!res.headersSent)
                 res.json(payload);
         };
@@ -488,14 +516,17 @@ export function createApp({ store, config }) {
                 return;
             done({ timed_out: false, message: store.getMessage(agentId, event.message_id, false) });
         };
-        const onClose = () => {
-            clearTimeout(timer);
-            store.off("message", onMessage);
-            releaseWatcher();
+        const onLink = (event) => {
+            if (event.agent_id !== agentId)
+                return;
+            const [link] = store.linksFor(agentId, { linkId: event.link_id });
+            done({ timed_out: false, message: null, link });
         };
         const timer = setTimeout(() => done({ timed_out: true, message: null }), timeoutSeconds * 1000);
         store.on("message", onMessage);
-        req.once("close", onClose);
+        if (watcher)
+            store.on("link", onLink);
+        req.once("close", stop);
     });
     app.use("/api", api);
     // --- Erreurs --------------------------------------------------------------