@agifyai/leadify-mcp 9.14.0 → 9.15.0

package/README.md

@@ -211,9 +211,9 @@ Les corrections ajoutent un fait immuable et mettent à jour le snapshot
 courant dans la même opération ; elles exigent un motif. Il n’existe aucun tool
 de suppression de participation ou de preuve. Archiver un événement le retire
 des sélecteurs courants sans effacer son historique. Les champs legacy
-`congress_presence`, `next_congress`, `next_congress_date` et `card_congress`
-restent disponibles pour compatibilité/export, mais ne sont jamais synchronisés
-depuis ce modèle.
+`congress_presence`, `next_congress` et `next_congress_date` restent disponibles
+pour compatibilité/export, mais ne sont jamais synchronisés depuis ce modèle.
+L'ancienne carte `card_congress` est supprimée (PRD-2831) et refusée à l'écriture.
 
 Événements d’une personne :
 
@@ -277,6 +277,7 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `get_follow_up_cadence` | Rythme de relance de l'organisation (lecture seule). |
 | `get_prospect_approach` | Avant d'écrire à une personne : son Approche (quotidien, problématique, ce qu'elle veut, ce qu'on lui apporte). |
 | `list_outreach_review_queue` | La file « À valider » de Leadify (page `/to-review`) en un appel, en lecture seule : filtres campagne, canal, type de message et état (`TO_REVIEW` par défaut), `total`, `counts`, `truncated`. Le texte des messages seulement avec `include_text`. |
+| `revise_review_queue_message` | Remplacer le texte d'**un** message en `TO_REVIEW`, à la demande explicite du relecteur, au nom de l'agent nommé par `LEADIFY_EXTERNAL_AGENT_NAME` : relecture complète en réponse, version attendue, clé d'idempotence, limites du canal. Le message reste à valider : rien ne valide, ne programme, n'envoie ni ne refuse. Organisation d'Agify seulement. |
 | `preview_move_leads` | Essai à blanc du déplacement de fiches vers un autre groupe de la même organisation : sélection par identifiants, vue ou filtre (500 fiches au plus par appel, lots ensuite), refus par fiche avec motif, doublons dans le groupe cible, champs de schéma et relations à ajouter, blocages et empreinte du plan. |
 | `move_leads` | Appliquer un déplacement prévisualisé ; exige l'empreinte de la prévisualisation et une clé d'idempotence. La fiche garde son identifiant et tout son historique ; jamais de fusion. |
 | `undo_move_leads` / `get_lead_move` | Annuler ou relire une opération de déplacement par son identifiant. |
@@ -502,17 +503,38 @@ de son extrait de 500 caractères.
 les messages de campagne qui attendent une décision humaine, dans l'ordre de la
 page, au plus 500, sans pagination. Filtres : `campaign_id`, `channel` (`EMAIL`,
 `LINKEDIN`), `message_type_id` et `state` (`TO_REVIEW` par défaut, `VALIDATED`,
-`CORRECTED`, `REFUSED`, ou `ALL`). Les identifiants des filtres viennent de
+`CORRECTED`, `REWRITTEN`, `REFUSED`, ou `ALL`). Les identifiants des filtres viennent de
 `filters.campaigns` et `filters.messageTypes`. Chaque message garde l'essentiel
 (prospect, entreprise, campagne, canal, étape, type, départ prévu, créneau
-manqué, statut, objet) ; la révision, la date de création et les identifiants de
-campagne et de type, déjà dans `filters`, sont retirés. Sans le texte des
+manqué, statut, objet), sa `version`, et l'auteur de sa dernière modification
+(`lastEditedBy` : `none`, `human` ou `agent`, avec `lastEditedByName`) ; la date de
+création et les identifiants de campagne et de type, déjà dans `filters`, sont
+retirés. `decisions` sépare les messages validés : `validatedAsIs`,
+`validatedAfterAgentRewrite`, `correctedByHuman`. Sans le texte des
 messages, la file réelle de 73 messages tient en environ 30 000 caractères, sous
 la limite de 50 000 d'Hermès ; `include_text: true` ajoute `body`, le message
 entier (environ 500 caractères de plus par message) : au-delà d'une quarantaine
 de messages, filtrer d'abord. Si `truncated` vaut `true`, filtrer par campagne.
-Aucun outil ne valide, corrige ou refuse : cela reste humain. Route :
-`GET /api/outreach-review/queue` (permission `read`).
+Route : `GET /api/outreach-review/queue` (permission `read`).
+
+`revise_review_queue_message` remplace le texte d'un seul message en `TO_REVIEW`,
+à la demande explicite du relecteur : le corps, et l'objet d'un email. Le message
+reste à valider ; l'état, l'heure de départ, la campagne, le destinataire et le
+canal ne changent pas. Entrées : `organization_id`, `message_id`, `body`,
+`subject` (facultatif), `expected_version`, `idempotency_key`. La réponse est une
+relecture complète : texte enregistré, `version`, auteur `agent`, état et
+`history` (les textes précédents). Chaque écriture crée la version suivante sous
+un **nouvel identifiant** : utiliser `messageId` et `version` de la réponse pour la
+suite. Rejouer la même clé rend le même résultat (`replayed: true`). Refus sans
+écriture : `MESSAGE_NOT_TO_REVIEW`, `MESSAGE_VERSION_STALE`,
+`IDEMPOTENCY_KEY_REUSED`, `EDIT_INVALID` (note d'invitation LinkedIn : 300 caractères
+au plus ; message LinkedIn et email : 1 500 ; objet : 90 ; pas d'objet sur
+LinkedIn), `AGENT_REVISION_ORGANIZATION_FORBIDDEN` (organisation d'Agify seulement).
+Exige `LEADIFY_EXTERNAL_AGENT_NAME`, et une clé avec la permission `write`. Route :
+`POST /api/outreach-review/messages/:id/revise`.
+
+Aucun outil ne valide, ne programme, n'envoie ni ne refuse : cela reste humain, dans
+Leadify.
 
 ### Déplacer des prospects vers un autre groupe (PRD-2478)
 

package/dist/correlation.js

@@ -9,7 +9,7 @@ export const EXTERNAL_MISSION_VERSION = "external-agent.v1";
 const PROCESS_SESSION = randomUUID().replace(/-/g, "").slice(0, 16);
 export class ExternalAgentNameMissingError extends Error {
     constructor() {
-        super(`${EXTERNAL_AGENT_ENV} n'est pas défini : une écriture de qualification doit être faite au nom d'un agent identifié. ` +
+        super(`${EXTERNAL_AGENT_ENV} n'est pas défini : une écriture de qualification ou une réécriture de message doit être faite au nom d'un agent identifié. ` +
             `Lancez le MCP avec ${EXTERNAL_AGENT_ENV}=<Nom> (par exemple Louise). Les lectures restent disponibles sans ce nom.`);
         this.name = "ExternalAgentNameMissingError";
     }

package/dist/tools/leads.js

@@ -279,7 +279,7 @@ export function registerLeadTools(server, client = getClient()) {
         "An unknown field is refused with the name of the closest existing field: declare a new field first with `update_schema`. " +
         "`expect` (optional) protects against overwriting a newer value: pass, for each field you depend on, the value you read " +
         "({ property_name, value }). The write is refused with LEAD_WRITE_PRECONDITION_FAILED, and the value actually in place is " +
-        "returned, if any of them changed since your read. A field that was absent is not the same as null. Without `expect`, the write is unconditional. " +
+        "returned, if any of them changed since your read. To protect the first write of an empty field, expect null: it matches a field that is null or absent. Without `expect`, the write is unconditional. " +
         "`reason` (optional) is one sentence saying why you change the lead; it is recorded in the lead history. " +
         "For bulk updates across many leads, call this tool once per lead. A write during a platform agent run on this lead (external agent only) is refused with 409 QUALIFICATION_RUN_IN_PROGRESS (runId in the answer); nothing is written: wait for the run to end, read the lead again, then retry.", {
         lead_id: z.string().describe("ID of the lead to update."),
@@ -290,7 +290,7 @@ export function registerLeadTools(server, client = getClient()) {
         expect: z
             .array(z.object({
             property_name: z.string().trim().min(1).describe("Field you read."),
-            value: z.unknown().describe("Exact value you read for that field. Required key (null means the field held null)."),
+            value: z.unknown().describe("Exact value you read for that field. Required key; null means the field was empty (null or absent)."),
         }).strict())
             .optional()
             .describe("Optional preconditions: the values you read earlier. The write is refused (LEAD_WRITE_PRECONDITION_FAILED, with the current values) if any field no longer holds its expected value. Deep equality, checked in the same transaction as the write."),

package/dist/tools/outreach_review.d.ts

@@ -1,11 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type LeadifyClient } from "../client.js";
-export declare const OUTREACH_REVIEW_TOOL_NAMES: readonly ["list_outreach_review_queue"];
-export declare const OUTREACH_REVIEW_STATES: readonly ["ALL", "TO_REVIEW", "VALIDATED", "CORRECTED", "REFUSED"];
+export declare const OUTREACH_REVIEW_TOOL_NAMES: readonly ["list_outreach_review_queue", "revise_review_queue_message"];
+export declare const OUTREACH_REVIEW_STATES: readonly ["ALL", "TO_REVIEW", "VALIDATED", "CORRECTED", "REWRITTEN", "REFUSED"];
 export declare const OUTREACH_REVIEW_CHANNELS: readonly ["EMAIL", "LINKEDIN"];
-type Client = Pick<LeadifyClient, "get">;
+type Client = Pick<LeadifyClient, "get" | "post">;
 /**
- * One queue item without what only a write would need (revision, createdAt) and
+ * One queue item, with version (the revision a write must name), without createdAt and
  * without the campaign and message type ids, which filters.campaigns and
  * filters.messageTypes carry once. The body only with include_text.
  */

package/dist/tools/outreach_review.js

@@ -1,29 +1,32 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
+import { ExternalAgentNameMissingError, externalAgentName } from "../correlation.js";
 import { handleToolError } from "../types.js";
-// PRD-2815 — la file « À valider » de Leadify (page /to-review) en lecture seule,
-// par la route serveur GET /api/outreach-review/queue. Valider, corriger ou
-// refuser reste humain : aucune écriture ici.
-export const OUTREACH_REVIEW_TOOL_NAMES = ["list_outreach_review_queue"];
-export const OUTREACH_REVIEW_STATES = ["ALL", "TO_REVIEW", "VALIDATED", "CORRECTED", "REFUSED"];
+// PRD-2815 — la file « À valider » de Leadify (page /to-review), par la route serveur
+// GET /api/outreach-review/queue. Une seule écriture : un agent nommé remplace le texte
+// d'un message à valider, par POST /api/outreach-review/messages/:id/revise. Valider,
+// programmer, envoyer ou refuser reste humain : aucun outil ici ne le fait.
+export const OUTREACH_REVIEW_TOOL_NAMES = ["list_outreach_review_queue", "revise_review_queue_message"];
+export const OUTREACH_REVIEW_STATES = ["ALL", "TO_REVIEW", "VALIDATED", "CORRECTED", "REWRITTEN", "REFUSED"];
 export const OUTREACH_REVIEW_CHANNELS = ["EMAIL", "LINKEDIN"];
 const id = z.string().trim().min(1).max(200);
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const REVISE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 const object = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
 /** One line of JSON: an agent runtime sets aside tool results above 50,000 characters. */
 const compact = (data) => ({ content: [{ type: "text", text: JSON.stringify(data) }] });
 /**
- * One queue item without what only a write would need (revision, createdAt) and
+ * One queue item, with version (the revision a write must name), without createdAt and
  * without the campaign and message type ids, which filters.campaigns and
  * filters.messageTypes carry once. The body only with include_text.
  */
 export function projectReviewItem(item, includeText) {
     const i = object(item);
     const result = {
-        id: i.id, leadId: i.leadId, leadName: i.leadName, companyName: i.companyName, campaignName: i.campaignName,
+        id: i.id, version: i.revision, leadId: i.leadId, leadName: i.leadName, companyName: i.companyName, campaignName: i.campaignName,
         channel: i.channel, step: i.step, stepKind: i.stepKind, messageTypeName: object(i.messageType).name ?? null,
         plannedDepartureAt: i.plannedDepartureAt, missedSlot: i.missedSlot, status: i.status, editedByHuman: i.editedByHuman,
-        subject: i.subject,
+        lastEditedBy: i.lastEditedBy, lastEditedByName: i.lastEditedByName, subject: i.subject,
     };
     if (includeText)
         result.body = i.body;
@@ -32,16 +35,19 @@ export function projectReviewItem(item, includeText) {
 export function registerOutreachReviewTools(server, client = getClient()) {
     server.tool("list_outreach_review_queue", "The Leadify 'À valider' queue (page /to-review) in ONE call: the campaign messages waiting for a human decision, in " +
         "the page's order. Read-only: validating, correcting or refusing a message stays human, in Leadify. Answer: " +
-        "{organizationId, state, limit, total, counts {all, toReview, validated, corrected, refused}, truncated, items, " +
-        "filters {campaigns [{id, name}], messageTypes [{id, name}]}, notContactedToday {count, reasons}}. Each item: id, " +
+        "{organizationId, state, limit, total, counts {all, toReview, validated, corrected, rewritten, refused}, " +
+        "decisions {validatedAsIs, validatedAfterAgentRewrite, correctedByHuman}, truncated, items, " +
+        "filters {campaigns [{id, name}], messageTypes [{id, name}]}, notContactedToday {count, reasons}}. decisions splits the " +
+        "validated messages by who last wrote their text. Each item: id, version (what revise_review_queue_message expects), " +
         "leadId, leadName, companyName, campaignName, channel, step, stepKind, messageTypeName, plannedDepartureAt, " +
-        "missedSlot, status (TO_REVIEW, APPROVED, SCHEDULED, SENT, REJECTED), editedByHuman, subject. To stay well under " +
+        "missedSlot, status (TO_REVIEW, APPROVED, SCHEDULED, SENT, REJECTED), editedByHuman, lastEditedBy (none, human or agent), " +
+        "lastEditedByName (the agent's name), subject. To stay well under " +
         "50,000 characters, the message text is left out by default (about 30,000 characters for 73 messages); " +
         "include_text=true adds body, the whole message, about 500 characters more per message (about 68,000 for those 73): " +
         "above about 40 messages, narrow with campaign_id, channel or message_type_id first. At most 500 messages, no pagination: when truncated " +
         "is true, filter by campaign_id. Pass the ids found in filters.campaigns and filters.messageTypes.", {
         organization_id: id.describe("Organization to read. Must be in the API key's scope."),
-        state: z.enum(OUTREACH_REVIEW_STATES).optional().describe("TO_REVIEW (default): waiting for validation. VALIDATED, CORRECTED, REFUSED: decided in the last 7 days. ALL: TO_REVIEW plus the messages validated, scheduled, sent or refused in the last 7 days."),
+        state: z.enum(OUTREACH_REVIEW_STATES).optional().describe("TO_REVIEW (default): waiting for validation. VALIDATED, CORRECTED, REFUSED: decided in the last 7 days. CORRECTED: last written by a human. REWRITTEN: last written by an agent. ALL: TO_REVIEW plus the messages validated, scheduled, sent or refused in the last 7 days."),
         campaign_id: id.optional().describe("Only this campaign (filters.campaigns[].id)."),
         channel: z.enum(OUTREACH_REVIEW_CHANNELS).optional().describe("EMAIL or LINKEDIN."),
         message_type_id: id.optional().describe("Only this message type (filters.messageTypes[].id)."),
@@ -59,4 +65,34 @@ export function registerOutreachReviewTools(server, client = getClient()) {
             return handleToolError(error);
         }
     }));
+    server.tool("revise_review_queue_message", "Replace the text of ONE campaign message waiting in the Leadify 'À valider' queue, at the reviewer's explicit request. " +
+        "Changes only the body, and the subject of an email. The message stays TO_REVIEW: state, planned departure, campaign, " +
+        "recipient and channel never change, and the reviewer still validates it by hand in Leadify. Nothing here validates, " +
+        "schedules, sends or refuses. Each write creates the next version under a NEW id: use the returned messageId and version " +
+        "for anything after it. The previous text stays in history. Answer, read back after writing: {organizationId, messageId, " +
+        "previousMessageId, version, status, campaignId, leadId, channel, step, subject, body, lastEditedBy, lastEditedByName, " +
+        "unchanged, replayed, latestMessageId, updatedAt, history [{messageId, version, status, subject, body, lastEditedBy, " +
+        "lastEditedByName, createdAt}]}. Replaying the same idempotency_key with the same call returns the same message " +
+        "(replayed: true). Refusals, nothing written: MESSAGE_NOT_TO_REVIEW (APPROVED, SCHEDULED, SENT, REJECTED...), " +
+        "MESSAGE_VERSION_STALE (reread the queue, latestMessageId gives the current one), IDEMPOTENCY_KEY_REUSED, EDIT_INVALID " +
+        "(empty, too long: LinkedIn invitation note 300 characters, LinkedIn message 1500, email 1500 and subject 90; or a subject " +
+        "on LinkedIn), AGENT_REVISION_ORGANIZATION_FORBIDDEN. Requires LEADIFY_EXTERNAL_AGENT_NAME: the author is noted as that agent.", {
+        organization_id: id.describe("Organization of the message. Must be in the API key's scope."),
+        message_id: id.describe("id of the message in list_outreach_review_queue."),
+        body: z.string().min(1).max(16000).describe("The whole new message text, not a diff."),
+        subject: z.string().min(1).max(600).optional().describe("New subject, email only. Omit it to keep the current subject."),
+        expected_version: z.number().int().min(1).describe("version of the message as read in list_outreach_review_queue."),
+        idempotency_key: z.string().trim().min(8).max(200).describe("A new unique key per new text; reuse it only to replay the same call after an uncertain result."),
+    }, REVISE, (async ({ organization_id, message_id, body, subject, expected_version, idempotency_key }) => {
+        try {
+            if (!externalAgentName())
+                throw new ExternalAgentNameMissingError();
+            return compact(await client.post(`/api/outreach-review/messages/${encodeURIComponent(message_id)}/revise`, {
+                organizationId: organization_id, body, ...(subject === undefined ? {} : { subject }), expectedVersion: expected_version, idempotencyKey: idempotency_key,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agifyai/leadify-mcp",
-  "version": "9.14.0",
+  "version": "9.15.0",
   "description": "MCP server for Leadify lead management API",
   "type": "module",
   "main": "dist/index.js",