@imenam/mcp-messenger 1.0.9 → 1.0.11

package/dist/src/mcp/tools.js

@@ -55,11 +55,15 @@ export const TOOLS = [
     },
     {
         name: "list_threads",
-        description: "List the conversations visible from this mailbox, most recently active first, with their name, participants and unread count. This is the readable map of the ongoing work: prefer it over list_messages when you want to know what is being discussed rather than what arrived last. A thread with no name falls back to the subject of its opening message — name it with rename_thread.",
+        description: "List the conversations visible from this mailbox, most recently active first, with their name, participants and unread count. This is the readable map of the ongoing work: prefer it over list_messages when you want to know what is being discussed rather than what arrived last. Set with_mailbox to see everything exchanged with one correspondent. A thread with no name falls back to the subject of its opening message — name it with rename_thread.",
         inputSchema: {
             type: "object",
             properties: {
                 unread_only: { type: "boolean", description: "Keep only threads with unread messages." },
+                with_mailbox: {
+                    type: "string",
+                    description: "A correspondent's mailbox address, as listed by list_agents: keep only the threads shared with that mailbox. This is how you review what you have exchanged with someone — a conversation is a thread, not a stack of messages.",
+                },
                 search: { type: "string", description: "Free text matched against thread name, description and subject." },
                 limit: { type: "number", description: "1-100, defaults to 25." },
             },
@@ -68,16 +72,25 @@ export const TOOLS = [
     },
     {
         name: "list_agents",
-        description: "List the other agents known to the mailbox server, most recently active first, with their name and description. Your own mailbox is never listed — you cannot write to yourself. Use it to find the address of the agent you want to write to.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_name: {
+                    type: "string",
+                    description: "Name of one agent (project) to expand: lists every one of its session mailboxes in full. Omit it to get the whole directory, grouped.",
+                },
+            },
+            additionalProperties: false,
+        },
     },
     {
         name: "send_message",
-        description: "Send a message to one agent, identified by its mailbox address. A message has a single recipient: to reach several agents, send each one its own message. Set reply_to to answer an existing message and keep the thread together. Never write a mailbox address in the body: the server attaches the sender and the recipient to every message, so an address copied by hand adds nothing and misleads as soon as it is wrong.",
+        description: "Send a message to one mailbox, identified by its address. A message has a single recipient: to reach several correspondents, send each one its own message. Set reply_to to answer an existing message and keep the thread together. Never write a mailbox address in the body: the server attaches the sender and the recipient to every message, so an address copied by hand adds nothing and misleads as soon as it is wrong.",
         inputSchema: {
             type: "object",
             properties: {
-                to: { type: "string", description: "Recipient agent id (mailbox address). Exactly one recipient." },
+                to: { type: "string", description: "Recipient mailbox address, as listed by list_agents. Exactly one recipient." },
                 subject: { type: "string", description: "Short subject line." },
                 body: {
                     type: "string",
@@ -97,13 +110,13 @@ export const TOOLS = [
     },
     {
         name: "list_messages",
-        description: "List messages in this agent's mailbox, newest first, with a short preview. Filter by folder, unread state, sender, thread or free text.",
+        description: "List messages in this mailbox, newest first, with a short preview. Filter by folder, unread state, sender, thread or free text.",
         inputSchema: {
             type: "object",
             properties: {
                 folder: { type: "string", description: FOLDER_HINT + " Defaults to inbox." },
                 unread_only: { type: "boolean", description: "Keep only unread messages." },
-                from: { type: "string", description: "Only messages sent by this agent id." },
+                from: { type: "string", description: "Only messages sent by this mailbox address." },
                 thread_id: { type: "string", description: "Only messages of this thread." },
                 search: { type: "string", description: "Free text matched against subject and body." },
                 limit: { type: "number", description: "1-100, defaults to 25." },
@@ -127,7 +140,7 @@ export const TOOLS = [
     },
     {
         name: "get_thread",
-        description: "Read every message of a thread visible to this agent, oldest first — the full conversation.",
+        description: "Read every message of a thread visible to this mailbox, oldest first — the full conversation.",
         inputSchema: {
             type: "object",
             properties: { thread_id: { type: "string", description: "Thread id shown on any message." } },
@@ -164,7 +177,7 @@ export const TOOLS = [
     },
     {
         name: "delete_messages",
-        description: "Send messages to the trash folder, or erase them from this mailbox for good when permanent is true. Other recipients keep their own copy.",
+        description: "Send messages to the trash folder, or erase them from this mailbox for good when permanent is true. The other party keeps its own copy in its own mailbox.",
         inputSchema: {
             type: "object",
             properties: {
@@ -276,9 +289,15 @@ const schemas = {
     }),
     list_threads: z.object({
         unread_only: z.boolean().optional(),
+        with_mailbox: z.string().trim().min(1).optional(),
+        // Ancien nom du même filtre, plus publié mais toujours accepté : une session l'a pu
+        // apprendre avant la mise à jour. Sans cette entrée, zod l'écarterait en silence et
+        // l'agent recevrait tous ses fils en croyant les avoir filtrés.
+        with_agent: z.string().trim().min(1).optional(),
         search: z.string().trim().min(1).optional(),
         limit: z.number().int().optional(),
     }),
+    list_agents: z.object({ agent_name: z.string().trim().min(1).optional() }),
     create_folder: z.object({ name: z.string().min(1) }),
     delete_folder: z.object({ name: z.string().min(1) }),
     wait_for_message: z.object({ timeout_seconds: z.number().int().optional(), folder: z.string().optional() }),
@@ -371,39 +390,28 @@ export async function callTool(client, name, rawArgs) {
         }
         case "list_threads": {
             const input = schemas.list_threads.parse(args);
-            const threads = await client.listThreads(input);
+            // Une adresse désigne une boîte : les outils disent `with_mailbox`. Le protocole HTTP
+            // et le stockage gardent `with_agent`, du nom de la colonne, comme `thread_title`
+            // garde son nom face au `thread_name` des outils.
+            const correspondent = input.with_mailbox ?? input.with_agent;
+            const threads = await client.listThreads({
+                unread_only: input.unread_only,
+                search: input.search,
+                limit: input.limit,
+                with_agent: correspondent,
+            });
+            const scope = correspondent ? ` with ${correspondent}` : "";
             if (threads.length === 0)
-                return "No thread in this mailbox matching these filters.";
-            return [`${threads.length} thread(s):`, "", ...threads.map(formatThread)].join("\n");
+                return `No thread in this mailbox${scope} matching these filters.`;
+            return [`${threads.length} thread(s)${scope}:`, "", ...threads.map(formatThread)].join("\n");
         }
         case "list_agents": {
+            const input = schemas.list_agents.parse(args);
             const agents = await client.listAgents();
             if (agents.length === 0)
-                return "No other agent on this server yet.";
-            const directory = agents
-                .map((agent) => {
-                const flags = agent.registered ? "" : "never connected";
-                const names = formatAgentNames(agent);
-                const title = names ? `${agent.id} — ${names}` : agent.id;
-                // L'annuaire est classé par cette date : l'afficher rend l'ordre lisible.
-                const seen = agent.last_activity_at ? `last active ${agent.last_activity_at}` : "never active";
-                return [
-                    `• ${title}${flags ? ` (${flags})` : ""}`,
-                    `  ${agent.agent_description ?? agent.description ?? "no description"}`,
-                    `  ${seen}`,
-                ].join("\n");
-            })
-                .join("\n");
-            // Un nom d'agent est celui d'un projet, pas d'une session : plusieurs boîtes le
-            // portent, y compris celle de l'appelant. Sans ce rappel, un agent croise son propre
-            // nom d'agent dans cette liste et prend la boîte d'une autre session pour la sienne.
-            return [
-                directory,
-                "",
-                "Addresses identify sessions; agent names do not. Several mailboxes above may carry the same",
-                "agent name as yours — they are other sessions of the same project, never you: your own mailbox",
-                "is never listed here. Always write to an address taken from this list, never to a name.",
-            ].join("\n");
+                return "No other mailbox on this server yet.";
+            const groups = groupByAgentName(agents);
+            return input.agent_name ? formatAgentGroup(groups, input.agent_name) : formatDirectory(groups);
         }
         case "send_message": {
             const input = schemas.send_message.parse(args);
@@ -555,6 +563,111 @@ async function renameMailbox(client, name, description) {
 function formatAgentNames(agent) {
     return [agent.agent_name, agent.display_name].filter(Boolean).join(" · ");
 }
+/** Boîtes détaillées sous un nom d'agent avant de renvoyer le reste à `agent_name`. */
+const SESSIONS_SHOWN_PER_AGENT = 4;
+const NO_AGENT_NAME = "unnamed agent";
+/**
+ * Deux boîtes sans nom d'agent ne sont pas deux sessions du même projet : rien ne le dit.
+ * Chacune reste donc son propre groupe, là où un nom partagé les rassemble.
+ */
+function groupByAgentName(agents) {
+    const groups = new Map();
+    for (const agent of agents) {
+        const name = agent.agent_name?.trim() ?? "";
+        const key = name ? name.toLowerCase() : `\u0000${agent.id}`;
+        const group = groups.get(key);
+        if (group) {
+            group.mailboxes.push(agent);
+            group.description ??= agent.agent_description;
+        }
+        else {
+            groups.set(key, {
+                name: name || NO_AGENT_NAME,
+                key,
+                description: agent.agent_description,
+                mailboxes: [agent],
+            });
+        }
+    }
+    // L'annuaire arrive classé par activité décroissante : l'ordre d'insertion place en tête
+    // l'agent dont une session a bougé le plus récemment, et ses boîtes dans le même ordre.
+    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) {
+    const seen = agent.last_activity_at ? `last active ${agent.last_activity_at}` : "never active";
+    const flags = agent.registered ? "" : " · never connected";
+    return `  • ${agent.id} — ${agent.display_name ?? "no mailbox name"} · ${seen}${flags}`;
+}
+/**
+ * Rappel joint à toute réponse de l'annuaire.
+ *
+ * Un nom d'agent est celui d'un projet, pas d'une session : plusieurs boîtes le portent, y
+ * compris celle de l'appelant. Sans ce rappel, un agent croise son propre nom d'agent dans
+ * cette liste et prend la boîte d'une autre session pour la sienne. Le groupement rend le
+ * nom encore plus visible que l'adresse : la mise en garde compte d'autant plus.
+ */
+const DIRECTORY_FOOTER = [
+    "Addresses identify sessions; agent names do not. Several mailboxes above may carry the same",
+    "agent name as yours — they are other sessions of the same project, never you: your own mailbox",
+    "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) {
+    const mailboxes = groups.reduce((total, group) => total + group.mailboxes.length, 0);
+    const blocks = groups.map((group) => {
+        const sessions = group.mailboxes.length;
+        const lines = [`${group.name} — ${sessions} session(s)`];
+        if (group.description)
+            lines.push(`  ${group.description}`);
+        // 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));
+        if (shown.length < sessions) {
+            lines.push(`  … ${sessions - shown.length} more session(s) — list_agents with agent_name: "${group.name}" lists them all.`);
+        }
+        return lines.join("\n");
+    });
+    // Un agent par bloc, séparés par une ligne vide : le groupe est l'unité de lecture.
+    return [
+        `${groups.length} agent(s), ${mailboxes} mailbox(es):`,
+        "",
+        blocks.join("\n\n"),
+        "",
+        ...DIRECTORY_FOOTER,
+    ].join("\n");
+}
+/** Toutes les sessions d'un agent, décrites une par une : le second niveau de l'annuaire. */
+function formatAgentGroup(groups, requested) {
+    const wanted = requested.trim().toLowerCase();
+    const group = groups.find((g) => g.name.toLowerCase() === wanted);
+    if (!group) {
+        const known = groups.map((g) => g.name).join(", ");
+        throw new Error(`No agent named "${requested}" on this server. Known agent names: ${known}`);
+    }
+    const blocks = group.mailboxes.map((agent) => {
+        const seen = agent.last_activity_at ? `last active ${agent.last_activity_at}` : "never active";
+        return [
+            `• ${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"}`,
+        ]
+            .filter(Boolean)
+            .join("\n");
+    });
+    return [
+        `${group.name} — ${group.mailboxes.length} session(s), most recently active first:`,
+        group.description ?? null,
+        "",
+        ...blocks,
+        "",
+        ...DIRECTORY_FOOTER,
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+}
 async function renameThread(client, threadId, name, description) {
     const thread = await client.setThreadLabel(threadId, { title: name, description });
     return [

package/dist/src/server/app.js

@@ -45,6 +45,7 @@ const threadLabelSchema = z
 });
 const listThreadsQuerySchema = z.object({
     unread_only: z.coerce.boolean().optional(),
+    with_agent: z.string().trim().min(1).optional(),
     search: z.string().trim().min(1).optional(),
     limit: z.coerce.number().int().min(1).max(100).optional(),
     offset: z.coerce.number().int().min(0).optional(),
@@ -78,6 +79,14 @@ const waitQuerySchema = z.object({
     watcher: z.enum(["true", "1"]).optional(),
 });
 const loginSchema = z.object({ token: z.string().min(1).max(1024) });
+const adminThreadsSchema = z.object({
+    search: z.string().trim().min(1).optional(),
+    agent: z.string().trim().min(1).optional(),
+    unread_only: z.enum(["true", "1"]).optional(),
+    priority: z.enum(PRIORITIES).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
+});
 const adminListSchema = z.object({
     search: z.string().trim().min(1).optional(),
     agent: z.string().trim().min(1).optional(),
@@ -161,12 +170,26 @@ export function createApp({ store, config }) {
     admin.get("/messages/:id", (req, res) => {
         res.json(store.getMessageAdmin(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);
+        res.json({
+            threads: store.listAllThreadsAdmin({
+                search: query.search,
+                agent: query.agent,
+                unread_only: query.unread_only !== undefined,
+                priority: query.priority,
+                limit: query.limit,
+                offset: query.offset,
+            }),
+        });
+    });
     admin.get("/threads/:id", (req, res) => {
         const threadId = String(req.params.id);
-        const messages = store.listAllMessages({ thread_id: threadId, limit: 100 });
+        const messages = store.listThreadAdmin(threadId);
         if (messages.length === 0)
             throw new MessengerError(`thread not found: ${threadId}`, 404);
-        res.json({ thread_id: threadId, thread: store.getThreadInfo(threadId), messages: messages.slice().reverse() });
+        res.json({ thread_id: threadId, thread: store.getThreadInfo(threadId), messages });
     });
     app.use("/admin", admin);
     // Porte d'entrée de tout le reste : aucune requête n'est servie sans jeton valide. Le