@agifyai/leadify-mcp 9.13.0 → 9.14.1

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 :
 
@@ -282,7 +282,7 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `undo_move_leads` / `get_lead_move` | Annuler ou relire une opération de déplacement par son identifiant. |
 | `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter` (`subject` : employeur ou personne). |
 | `get_lead` | Récupérer les détails complets d'un lead par son ID. |
-| `update_lead` | Mettre à jour un ou plusieurs champs d'un lead existant. |
+| `update_lead` | Mettre à jour un ou plusieurs champs d'un lead existant. `expect` (facultatif) : valeurs lues, l'écriture est refusée (`LEAD_WRITE_PRECONDITION_FAILED`) si l'une a changé depuis ; `reason` (facultatif) : motif noté dans l'historique. Ne s'écrit jamais `qualification_document` par cet outil. |
 | `clear_lead_field` | Effacer irréversiblement une valeur stockée, sans modifier le schéma du groupe. Exige la confirmation explicite `clear_lead_field`. |
 | `list_events` | Lister les événements tenant-scoped, filtrables par type (`event_types`) ; les événements archivés sont masqués par défaut. |
 | `get_event` | Lire un événement partagé, son type, son état d’archivage et ses nombres d’entreprises et de personnes rattachées. |
@@ -784,3 +784,33 @@ changent pas l’état du message et n’exposent pas l’enveloppe fournisseur
 
 Pour un signal daté, `signal_upsert.date_evidence` fournit le passage source qui
 établit `date`. Le serveur conserve cette preuve ; une date sans preuve est refusée.
+
+## Qualification V3 pour un agent externe (PRD-2831)
+
+Un agent externe (Louise, profil Hermes `huntify`) qualifie par les mêmes routes que l'agent de la plateforme, sous son nom. Le MCP pose seul la **corrélation** de chaque écriture : `triggerRunId = agentRunId = traceId = external:<agent>:<session>`, `missionVersion = external-agent.v1`, `author = { kind: external_agent, name }`. Le modèle ne la fournit jamais.
+
+- `LEADIFY_EXTERNAL_AGENT_NAME` (par exemple `Louise`) est obligatoire pour **écrire** ; `<agent>` est ce nom en minuscules, sans espace. Sans lui, les écritures sont refusées avant tout appel serveur, avec un message clair ; les lectures marchent.
+- `<session>` est un identifiant aléatoire par processus du MCP, ou le `session_ref` facultatif de l'appel. Garder le même `session_ref` pour les propositions de contacts et leur finalisation.
+- Les écritures avec essai à blanc (`dry_run`) valent `true` par défaut : relire le résultat, puis renvoyer `dry_run=false`. La clé d'idempotence est dérivée du contenu si elle n'est pas donnée.
+- Refus rendus lisibles avec une consigne (`next_step`) : `QUALIFICATION_RUN_IN_PROGRESS` (attendre la fin du passage), refus du contrat avec chaque chemin, gardes périmées (relire le contexte), `QUALIFICATION_RULES_UNAVAILABLE`.
+
+| Outil | Rôle |
+| --- | --- |
+| `get_qualification_context` | Entrée de l'agent, fiche actuelle avec ses auteurs, politique des champs, gardes de fraîcheur (lecture). |
+| `get_qualification_document` | Fiche actuelle, gardes, et les 10 dernières versions (lecture). |
+| `get_qualification_rules` | Règles de la qualification (entreprise ou personne) lues au registre de prompts (lecture). |
+| `validate_qualification_section` | Essai à blanc d'une case de la fiche, sans écriture. |
+| `submit_qualification_patch` | Écrit un patch de la fiche, jugé par le contrat. `reason` obligatoire, gardée par le serveur sur la version (historique de la fiche). |
+| `list_qualification_versions` / `get_qualification_version` | Versions de la fiche, résumé puis version complète. |
+| `restore_qualification_version` | Restaure une version (`dry_run` par défaut, raison obligatoire). |
+| `mark_for_requalification` | Marque la fiche à requalifier, sans lancer de passage. |
+| `qualification_write_signal` / `qualification_record_event` | Signal daté et sourcé ; événement et participation (entreprise ou personne). |
+| `qualification_search_employer` / `qualification_link_employer` | Cherche l'employeur (reçu de recherche), puis rattache la personne avec preuve. |
+| `qualification_read_known_contacts` / `qualification_propose_contacts` / `qualification_finalize_contacts` / `qualification_readback_contact_proposal` / `qualification_discover_contact` | Contacts découverts : vérifier les doublons, proposer, finaliser (ou relire avec `readback_only`), relire une proposition, découverte depuis une entreprise. |
+| `qualification_enrich_email` / `qualification_geocode_location` | Courriel professionnel ; géocodage de la localisation. |
+| `qualification_get_working_corpus` / `qualification_save_working_corpus` | Corpus de recherche figé d'une entreprise. |
+| `qualification_read_history` / `qualification_read_employment_evidence` | Historique de qualification ; preuves d'un emploi. |
+
+## Consigne permanente : Louise (Hermes)
+
+Toute modification d'un outil, d'un schéma ou d'une description de ce MCP qui touche la qualification ou le Company Brain met à jour Louise (agente Hermes au profil `huntify`, dépôt `mayeulrougevin/hermes` : `profiles/huntify/skills/` et `profiles/huntify/mcp-servers/huntify-leadify/contract.json`) dans la même livraison.

package/dist/client.js

@@ -1,3 +1,4 @@
+import { externalAgentName } from "./correlation.js";
 import { LeadifyApiError } from "./types.js";
 export class LeadifyClient {
     baseUrl;
@@ -25,6 +26,10 @@ export class LeadifyClient {
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
         };
+        // PRD-2831 : le serveur note l'agent externe dans l'historique et refuse ses écritures pendant un passage.
+        const agent = externalAgentName();
+        if (agent)
+            headers["x-leadify-external-agent"] = encodeURIComponent(agent); // toujours encodé : le serveur décode
         const init = { method, headers };
         if (body !== undefined &&
             (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")) {

package/dist/correlation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Corrélation d'un agent externe (Louise) pour les écritures de qualification.
+ * Elle est posée par le MCP, jamais demandée au modèle : seul `session_ref`
+ * (facultatif) peut la préciser.
+ */
+export declare const EXTERNAL_AGENT_ENV = "LEADIFY_EXTERNAL_AGENT_NAME";
+export declare const EXTERNAL_MISSION_VERSION = "external-agent.v1";
+export declare class ExternalAgentNameMissingError extends Error {
+    constructor();
+}
+export interface ExternalCorrelation {
+    triggerRunId: string;
+    agentRunId: string;
+    traceId: string;
+    missionVersion: string;
+    author: {
+        kind: "external_agent";
+        name: string;
+    };
+}
+export declare function externalAgentName(env?: NodeJS.ProcessEnv): string | undefined;
+/** Identifiant de session externe : `external:<agent>:<session>`. Refuse sans nom d'agent. */
+export declare function externalRunId(sessionRef?: string): string;
+export declare function externalCorrelation(sessionRef?: string): ExternalCorrelation;
+/** Corrélation d'une lecture : le nom de l'agent n'est pas exigé, la lecture n'écrit rien. */
+export declare function readCorrelation(sessionRef?: string): ExternalCorrelation;
+/** Variante des routes dont la corrélation n'accepte pas `missionVersion` (proposition de contact). */
+export declare function externalCorrelationWithoutMission(sessionRef?: string): {
+    triggerRunId: string;
+    agentRunId: string;
+    traceId: string;
+    author: {
+        kind: "external_agent";
+        name: string;
+    };
+};
+/** `lead_group_id` -> `leadGroupId`, récursivement, pour les charges utiles décrites en snake_case. */
+export declare function camelizeKeys(value: unknown): unknown;

package/dist/correlation.js

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Corrélation d'un agent externe (Louise) pour les écritures de qualification.
+ * Elle est posée par le MCP, jamais demandée au modèle : seul `session_ref`
+ * (facultatif) peut la préciser.
+ */
+export const EXTERNAL_AGENT_ENV = "LEADIFY_EXTERNAL_AGENT_NAME";
+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é. ` +
+            `Lancez le MCP avec ${EXTERNAL_AGENT_ENV}=<Nom> (par exemple Louise). Les lectures restent disponibles sans ce nom.`);
+        this.name = "ExternalAgentNameMissingError";
+    }
+}
+export function externalAgentName(env = process.env) {
+    const name = env[EXTERNAL_AGENT_ENV]?.trim();
+    return name ? name.slice(0, 120) : undefined;
+}
+function cleanSessionRef(ref) {
+    const cleaned = (ref ?? "").trim().replace(/\s+/g, "-").slice(0, 80);
+    return cleaned || PROCESS_SESSION;
+}
+/** Identifiant de session externe : `external:<agent>:<session>`. Refuse sans nom d'agent. */
+export function externalRunId(sessionRef) {
+    const name = externalAgentName();
+    if (!name)
+        throw new ExternalAgentNameMissingError();
+    const agent = name.toLowerCase().replace(/\s+/g, "");
+    return `external:${agent}:${cleanSessionRef(sessionRef)}`;
+}
+export function externalCorrelation(sessionRef) {
+    const name = externalAgentName();
+    if (!name)
+        throw new ExternalAgentNameMissingError();
+    const id = externalRunId(sessionRef);
+    return {
+        triggerRunId: id,
+        agentRunId: id,
+        traceId: id,
+        missionVersion: EXTERNAL_MISSION_VERSION,
+        author: { kind: "external_agent", name },
+    };
+}
+/** Corrélation d'une lecture : le nom de l'agent n'est pas exigé, la lecture n'écrit rien. */
+export function readCorrelation(sessionRef) {
+    if (externalAgentName())
+        return externalCorrelation(sessionRef);
+    const id = `external:reader:${cleanSessionRef(sessionRef)}`;
+    return { triggerRunId: id, agentRunId: id, traceId: id, missionVersion: EXTERNAL_MISSION_VERSION, author: { kind: "external_agent", name: "Lecture seule" } };
+}
+/** Variante des routes dont la corrélation n'accepte pas `missionVersion` (proposition de contact). */
+export function externalCorrelationWithoutMission(sessionRef) {
+    const { missionVersion: _omit, ...rest } = externalCorrelation(sessionRef);
+    return rest;
+}
+/** `lead_group_id` -> `leadGroupId`, récursivement, pour les charges utiles décrites en snake_case. */
+export function camelizeKeys(value) {
+    if (Array.isArray(value))
+        return value.map(camelizeKeys);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, inner]) => [
+            key.replace(/_([a-z0-9])/g, (_m, c) => c.toUpperCase()),
+            camelizeKeys(inner),
+        ]));
+    }
+    return value;
+}

package/dist/server.js

@@ -1,5 +1,6 @@
 import { registerAgentOutreachTools } from "./tools/agent_outreach.js";
 import { registerQualificationRunTools } from "./tools/qualification_runs.js";
+import { registerQualificationTools } from "./tools/qualification.js";
 import { registerOutreachExclusionTools } from "./tools/outreach_exclusion.js";
 import { registerProspectionTrackingTools } from "./tools/prospection_tracking.js";
 import { registerOutreachReviewTools } from "./tools/outreach_review.js";
@@ -62,6 +63,7 @@ export function createServer() {
     registerPersonaTools(server);
     registerPipelineTools(server);
     registerQualificationRunTools(server);
+    registerQualificationTools(server);
     registerOutreachExclusionTools(server);
     registerProspectionTrackingTools(server);
     registerOutreachReviewTools(server);

package/dist/tools/context_workspace.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
-import { handleToolError, toolResult } from "../types.js";
+import { LeadifyApiError, handleToolError, toolError, toolResult } from "../types.js";
 const CONTEXT_KIND = "company_brain";
 const MAX_READINESS_ISSUES = 20;
 const ACTIVE_CONTEXT_SECTIONS = [
@@ -12,11 +12,47 @@ const ACTIVE_CONTEXT_SECTIONS = [
 ];
 const shortText = z.string().trim().max(500);
 const longText = z.string().trim().max(20_000);
+const EVIDENCE_HELP = "Evidence references that support this section, written freely as plain text (up to 100). They are NOT identifiers created by the server: " +
+    "write a public URL, a document path (for example a Company Brain note of Agify with its path), or a short dated internal proof " +
+    "(e.g. \"Call with the CEO, 2026-10-30: pricing confirmed\"). At least one non-empty reference per section is required to publish; [] blocks publication.";
+const MISSING_EVIDENCE_CODE = "MISSING_REQUIRED_EVIDENCE";
+const MISSING_EVIDENCE_NEXT_STEP = "Each section needs at least one evidence reference (evidenceIds) to be published. Add one per section with update_company_brain_sections " +
+    "(a public URL, a document path, or a short dated internal proof, written as free text), then read again and publish.";
 const section = (value) => z.object({
     value,
-    evidenceIds: z.array(z.string().min(1)).max(100),
-    approved: z.boolean(),
+    evidenceIds: z.array(z.string().trim().min(1)).max(100).describe(EVIDENCE_HELP),
+    approved: z.boolean().describe("true once a human validated the section content; required to publish."),
 }).strict();
+const FORBIDDEN_SCOPE_NEXT_STEP = "FORBIDDEN_ORGANIZATION_SCOPE : écrire ou publier le Company Brain exige une clé d'API d'un administrateur de cette organisation (ou le bon organization_id).";
+const DRAFT_NOT_READY_NEXT_STEP = "Le brouillon reste ready:false. Lisez readiness.issues : chaque problème nomme sa section et son code (MISSING_REQUIRED_SECTION, EMPTY_REQUIRED_SECTION, UNAPPROVED_REQUIRED_SECTION -> approved:true, MISSING_REQUIRED_EVIDENCE -> evidenceIds). Corrigez avec update_company_brain_sections, puis publiez.";
+/** Consigne à joindre à un refus du serveur, selon son code ; undefined si rien à ajouter. */
+function companyBrainNextStep(error) {
+    const body = error.responseBody;
+    if (mentionsMissingEvidence(body) || mentionsMissingEvidence(error.message))
+        return MISSING_EVIDENCE_NEXT_STEP;
+    const code = body && typeof body === "object" ? body.error : undefined;
+    if (code === "READINESS_FAILED" || error.message === "READINESS_FAILED")
+        return DRAFT_NOT_READY_NEXT_STEP;
+    if (code === "FORBIDDEN_ORGANIZATION_SCOPE" || error.message === "FORBIDDEN_ORGANIZATION_SCOPE")
+        return FORBIDDEN_SCOPE_NEXT_STEP;
+    return undefined;
+}
+function withNextStepOnError(error) {
+    if (error instanceof LeadifyApiError) {
+        const next_step = companyBrainNextStep(error);
+        if (next_step)
+            return toolError(error.message, { statusCode: error.statusCode, response: error.responseBody, next_step });
+    }
+    return handleToolError(error);
+}
+function mentionsMissingEvidence(value) {
+    try {
+        return JSON.stringify(value)?.includes(MISSING_EVIDENCE_CODE) ?? false;
+    }
+    catch {
+        return false;
+    }
+}
 const sectionPatchSchema = z.object({
     identity: section(z.object({
         companyName: shortText.optional(),
@@ -192,7 +228,7 @@ export function registerContextWorkspaceTools(server, client = getClient()) {
     });
     server.registerTool("get_context_workspace", {
         title: "Read canonical versioned Context Workspace",
-        description: "Read the versioned Company Brain for one explicitly selected organization. " +
+        description: "Read the versioned Company Brain for one explicitly selected organization. If the draft readiness lists MISSING_REQUIRED_EVIDENCE, the result carries a next_step: add an evidence reference per section with update_company_brain_sections. " +
             "Returns the current draft plus the latest published version, with bounded readiness metadata. " +
             "Verticals, Offers and Personas use their dedicated non-versioned tools; historical GTM Playbook rows are not exposed.",
         inputSchema: {
@@ -203,7 +239,12 @@ export function registerContextWorkspaceTools(server, client = getClient()) {
         try {
             const params = new URLSearchParams({ organizationId: organization_id });
             const data = await client.get(`/api/context-workspace/${CONTEXT_KIND}`, params);
-            return toolResult(projectContextWorkspaceRead(data));
+            const projected = projectContextWorkspaceRead(data);
+            return toolResult(mentionsMissingEvidence(record(projected.draft).readiness)
+                ? { ...projected, next_step: MISSING_EVIDENCE_NEXT_STEP }
+                : record(record(projected.draft).readiness).ready === false
+                    ? { ...projected, next_step: DRAFT_NOT_READY_NEXT_STEP }
+                    : projected);
         }
         catch (error) {
             return handleToolError(error);
@@ -213,10 +254,13 @@ export function registerContextWorkspaceTools(server, client = getClient()) {
         title: "Update Company Brain sections",
         description: "Update only the named Company Brain sections. The MCP re-reads the current draft (or latest published version), merges only those sections, " +
             `and saves with optimistic concurrency. Allowed sections: ${ACTIVE_CONTEXT_SECTIONS.join(", ")}. ` +
-            "Historical fields moved to Vertical, Offer, Persona or Lead Group are rejected by the closed schema.",
+            "Historical fields moved to Vertical, Offer, Persona or Lead Group are rejected by the closed schema. " +
+            "Each section is { value, evidenceIds, approved }. To publish, every section needs at least one non-empty evidence reference in `evidenceIds`: " +
+            "free text, not a server-created id: a public URL, a document path (for example a Company Brain note of Agify with its path), " +
+            "or a short dated internal proof. Never send `evidenceIds: []` for a section you intend to publish.",
         inputSchema: {
             organization_id: z.string().trim().min(1).describe("Required organization ID; section writes require admin access."),
-            sections: sectionPatchSchema.describe("Only active Company Brain sections to change. Each section includes value, evidenceIds, and approved."),
+            sections: sectionPatchSchema.describe("Only active Company Brain sections to change. Each section includes value, evidenceIds (free-text evidence references, at least one to publish), and approved."),
             expected_revision: z.number().int().nonnegative().describe("Current draft revision, or 0 when no draft exists. Re-read first."),
             idempotency_key: z.string().trim().min(1).max(200).describe("Stable unique key for this exact section patch."),
         },
@@ -229,17 +273,20 @@ export function registerContextWorkspaceTools(server, client = getClient()) {
                 expectedRevision: expected_revision,
                 idempotencyKey: idempotency_key,
             });
-            return toolResult(compactDraft(data));
+            const draft = compactDraft(data);
+            const readiness = draft && typeof draft === "object" ? record(draft.readiness) : {};
+            return toolResult(readiness.ready === false ? { ...draft, next_step: DRAFT_NOT_READY_NEXT_STEP } : draft);
         }
         catch (error) {
-            return handleToolError(error);
+            return withNextStepOnError(error);
         }
     });
     server.registerTool("publish_context_workspace", {
         title: "Publish a ready Context Workspace draft",
         description: "Publish exactly one ready draft revision of the canonical Context Workspace. This is a consequential action: it requires " +
             "an organization-admin write key, the precise current draft revision, and `confirm_publish: true`. The server rejects incomplete " +
-            "content with its readiness reasons and rejects stale revisions without overwriting anything.",
+            "content with its readiness reasons and rejects stale revisions without overwriting anything. If it fails with MISSING_REQUIRED_EVIDENCE, " +
+            "add at least one evidence reference (evidenceIds: free-text URL, document path or short dated proof) to each section with update_company_brain_sections, then retry.",
         inputSchema: {
             organization_id: z.string().trim().min(1).describe("Required organization ID; publication is restricted to an admin key for this tenant."),
             expected_revision: z.number().int().positive().describe("Exact ready draft revision to publish, obtained from `get_context_workspace`."),
@@ -258,7 +305,7 @@ export function registerContextWorkspaceTools(server, client = getClient()) {
             return toolResult(compactPublished(data));
         }
         catch (error) {
-            return handleToolError(error);
+            return withNextStepOnError(error);
         }
     });
 }

package/dist/tools/leads.js

@@ -34,7 +34,7 @@ const leadInputSchema = z.record(z.unknown()).superRefine((lead, context) => {
     }
 });
 const leadUpdateSchema = z.object({
-    property_name: z.string().describe("Name of the field to update (e.g. 'email', 'status', 'card_analysis')."),
+    property_name: z.string().describe("Name of the field to update (e.g. 'email', 'status', 'jobTitle'). It must already exist in the lead group schema; declare a new one first with update_schema."),
     value: z.unknown().describe("New value for the field. location must use the canonical object; location.geo is forbidden."),
     is_select: z.boolean().optional().describe("If true, the field is created/updated as a 'select' dropdown type. Use for categorical fields like status, source, etc."),
 }).superRefine((update, context) => {
@@ -126,7 +126,7 @@ export function registerLeadTools(server, client = getClient()) {
         "upsert_person_leads_with_employment (after create_person_employment_evidence; no legal identity backfill is required). " +
         "Provide the group ID " +
         "and an array of lead objects with any combination of fields (email, firstName, " +
-        "lastName, company, jobTitle, phone, custom fields, card_* fields, percent_* " +
+        "lastName, company, jobTitle, phone, custom fields, percent_* " +
         "fields, etc.). Canonical relation fields are read-only here: use " +
         "manage_person_employment for employment links instead. Optionally specify which fields should be " +
         "treated as 'select' dropdowns in the UI. Returns the count of successfully " +
@@ -139,7 +139,7 @@ export function registerLeadTools(server, client = getClient()) {
             .describe("Array of lead objects. Each object is a key-value map of field names to values. " +
             "Common fields: email, firstName, lastName, company, jobTitle, phone, linkedin, " +
             "website, seniority, specialty, age. The company field is flat display text only and never creates an employment relationship or parent link. " +
-            "location must be {city, region?, postalCode?, countryCode, street?}; geo is computed by Leadify. Also supports card_* fields, " +
+            "location must be {city, region?, postalCode?, countryCode, street?}; geo is computed by Leadify. Also supports " +
             "percent_* fields and boolean flags (decisionMaking, excluded). Canonical relation fields are rejected."),
         is_select_fields: z
             .array(z.string())
@@ -270,20 +270,37 @@ export function registerLeadTools(server, client = getClient()) {
     // ── update_lead ────────────────────────────────────────────────────────
     server.tool("update_lead", "Update one or more fields on an existing lead. Each update specifies the field " +
         "name, new value, and optionally whether the field is a 'select' dropdown type. " +
-        "Supports all field types including special fields (card_*, percent_*, boolean flags " +
+        "Supports all field types including special fields (percent_*, boolean flags " +
         "like decisionMaking/excluded). When a configured canonical relation field is changed, " +
         "employment fields are refused: use manage_person_employment. Other relationship types retain their own service. Returns the updated lead. " +
         "location must be the canonical object {city, region?, postalCode?, countryCode, street?}; never submit geo. " +
-        "For bulk updates across many leads, call this tool once per lead.", {
+        "The qualification sheet (`qualification_document`) is never written by this tool: the server refuses it. " +
+        "Use the qualification tools (`submit_qualification_patch`) instead. " +
+        "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. 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."),
         updates: z
             .array(leadUpdateSchema)
             .min(1)
             .describe("Array of field updates to apply."),
-    }, async ({ lead_id, updates }) => {
+        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 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."),
+        reason: z.string().trim().min(1).max(500).optional().describe("One sentence saying why this change is made; recorded in the lead history."),
+    }, async ({ lead_id, updates, expect, reason }) => {
         try {
             const body = {
                 leadId: lead_id,
+                ...(expect ? { expect: expect.map((e) => ({ propertyName: e.property_name, value: e.value })) } : {}),
+                ...(reason ? { reason } : {}),
                 updates: updates.map((u) => ({
                     propertyName: u.property_name,
                     value: u.value,
@@ -298,15 +315,17 @@ export function registerLeadTools(server, client = getClient()) {
         }
     });
     server.tool("clear_lead_field", "Irreversibly remove one stored value from a lead without changing its lead-group schema. " +
-        "Canonical relationship fields require their dedicated relationship mutation. Always confirm with the user before calling this tool.", {
+        "Canonical relationship fields require their dedicated relationship mutation. Always confirm with the user before calling this tool. 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 change."),
         property_name: z.string().min(1).describe("Stored field name to clear. The field definition remains in the schema."),
         confirmation: z.literal("clear_lead_field").describe("Exact acknowledgement required before removing the stored value."),
-    }, async ({ lead_id, property_name }) => {
+        reason: z.string().trim().min(1).max(1_000).optional().describe("One sentence saying why the value is removed; recorded in the lead's history."),
+    }, async ({ lead_id, property_name, reason }) => {
         try {
             return toolResult(await client.delete("/clear-lead-field", {
                 leadId: lead_id,
                 propertyName: property_name,
+                ...(reason ? { reason } : {}),
             }));
         }
         catch (error) {

package/dist/tools/qualification.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type LeadifyClient } from "../client.js";
+import { type ToolResult } from "../types.js";
+/**
+ * Qualification V3 pour un agent externe (PRD-2831). Chaque écriture porte une
+ * corrélation posée par le MCP (voir correlation.ts). Les noms de champs des
+ * outils sont en snake_case ; les enveloppes du contrat de qualification
+ * (`patch`) restent telles que le contrat les écrit.
+ */
+type Client = Pick<LeadifyClient, "get" | "post" | "put">;
+/** Dernière version du contrat connue du MCP ; `contract_version` la remplace si le serveur en annonce une autre. */
+export declare const QUALIFICATION_CONTRACT_VERSION_DEFAULT = "3.8.0";
+/** Fait suivre chaque refus du serveur d'une consigne claire quand le code est connu. */
+export declare function qualificationError(error: unknown): ToolResult;
+/** Outils qui ne font que lire : annotés readOnlyHint, utilisables sans nom d'agent. */
+export declare const QUALIFICATION_READ_TOOL_NAMES: string[];
+export declare const QUALIFICATION_WRITE_TOOL_NAMES: string[];
+export declare const QUALIFICATION_TOOL_NAMES: string[];
+export declare function registerQualificationTools(server: McpServer, client?: Client): void;
+export {};

package/dist/tools/qualification.js

@@ -0,0 +1,411 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { ExternalAgentNameMissingError, camelizeKeys, externalCorrelation, externalCorrelationWithoutMission, readCorrelation, externalRunId, } from "../correlation.js";
+import { LeadifyApiError, handleToolError, toolError, toolResult } from "../types.js";
+/** Dernière version du contrat connue du MCP ; `contract_version` la remplace si le serveur en annonce une autre. */
+export const QUALIFICATION_CONTRACT_VERSION_DEFAULT = "3.8.0";
+const SIGNAL_CONTRACT_VERSION = "1.4.0";
+const EVENT_CONTRACT_VERSION = "1.1.0";
+const EMPLOYER_CONTRACT_VERSION = "2.0.0";
+const CONTACT_CONTRACT_VERSION = "1.0.0";
+const LOCATION_CONTRACT_VERSION = "1.0.0";
+const WORKING_CORPUS_CONTRACT_VERSION = "1.0.0";
+const id = z.string().trim().min(1).max(200);
+const org = id.describe("Organization ID, explicitly selected (discover_leadify_context). Never defaulted.");
+const sessionRef = z.string().trim().min(1).max(80).optional().describe("Optional. Names this working session; defaults to a random id per MCP process. The correlation (external:<agent>:<session>) is filled in by the MCP.");
+const dryRun = z.boolean().default(true).describe("Defaults to true: the server validates and answers without writing (persisted=false). Send false to write.");
+const idempotencyKey = z.string().trim().min(8).max(200).optional().describe("Stable key for this exact write. Omitted: derived from the content, so retrying the same call is safe.");
+const publicUrl = z.string().trim().url().max(2_000);
+const sourceUrls = z.array(publicUrl).min(1).max(10).describe("Public http(s) pages that prove the value.");
+const sourced = (value) => z.object({ value, source_urls: sourceUrls }).strict();
+const day = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "YYYY-MM-DD");
+const dayOrMonth = z.string().regex(/^\d{4}-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12]\d|3[01]))?$/, "YYYY-MM or YYYY-MM-DD");
+function derivedKey(prefix, payload) {
+    return `${prefix}-${createHash("sha256").update(JSON.stringify(payload)).digest("hex").slice(0, 40)}`;
+}
+/** Fait suivre chaque refus du serveur d'une consigne claire quand le code est connu. */
+export function qualificationError(error) {
+    if (error instanceof ExternalAgentNameMissingError)
+        return toolError(error.message);
+    if (!(error instanceof LeadifyApiError))
+        return handleToolError(error);
+    const body = (error.responseBody && typeof error.responseBody === "object" ? error.responseBody : {});
+    const code = typeof body.error === "string" ? body.error : undefined;
+    let next_step;
+    if (code === "QUALIFICATION_RUN_IN_PROGRESS") {
+        next_step = `Un passage de l'agent de qualification (runId ${String(body.runId ?? "inconnu")}) traite cette fiche. Rien n'a été écrit : attendez la fin du passage, relisez avec get_qualification_context, puis réessayez.`;
+    }
+    else if (code === "QUALIFICATION_RUN_CHECK_UNAVAILABLE") {
+        next_step = "Le serveur n'a pas pu vérifier si un passage est en cours. Rien n'a été écrit : réessayez dans un instant.";
+    }
+    else if (code === "QUALIFICATION_CONTRACT_REFUSED" && Array.isArray(body.issues)) {
+        const lines = body.issues
+            .map((i) => `${String(i.path || "(racine)")} : ${String(i.code)} - ${String(i.message)}`);
+        next_step = `Le contrat refuse l'écriture. Corrigez chaque chemin, puis réessayez (validate_qualification_section peut l'essayer case par case) :\n${lines.join("\n")}`;
+    }
+    else if (code && /^QUALIFY_SUBMISSION_(SCHEMA_STALE|LEAD_STALE|CONTEXT_CHANGED)$/.test(code)) {
+        next_step = "Les gardes (expected_schema_hash, expected_lead_revision, expected_context_digest) sont périmées. Rien n'a été écrit : relisez get_qualification_context, reprenez les gardes rendues, vérifiez que votre patch tient encore, puis réessayez.";
+    }
+    else if (code === "QUALIFICATION_RULES_NOT_CONFIGURED") {
+        next_step = "Le registre de prompts de la plateforme n'est pas configuré sur ce serveur. Réessayer ne servira à rien : prévenez l'administrateur, et n'improvisez pas les règles.";
+    }
+    else if (code === "QUALIFICATION_RULES_UNAVAILABLE") {
+        next_step = "Le registre de prompts de la plateforme ne répond pas. Aucune règle n'est rendue : réessayez dans un instant, sans improviser les règles.";
+    }
+    return toolError(error.message, {
+        statusCode: error.statusCode,
+        response: error.responseBody,
+        ...(next_step ? { next_step } : {}),
+    });
+}
+function run(client, fn) {
+    return Promise.resolve().then(fn).then(toolResult, qualificationError);
+}
+// -- Schémas de charges utiles, décrits en snake_case -----------------------
+const factualDate = z.object({ date: dayOrMonth, evidence: z.string().trim().min(1).describe("Quote or location that proves this date.") }).strict();
+const signalPayload = z.object({
+    evidence_type: z.enum(["PUBLIC_CONTENT", "PUBLIC_EVENT", "DIRECT_INTENT"]),
+    title: z.string().trim().min(1),
+    preview: z.string().trim().min(1),
+    content: z.string().trim().min(1).describe("Exactly 3 paragraphs separated by a blank line: the dated fact, the concrete substance, the commercial read."),
+    dates: z.object({
+        publication: factualDate.optional(),
+        update: factualDate.optional(),
+        event: z.object({ start: dayOrMonth, end: day.optional().describe("Exact day, YYYY-MM-DD."), evidence: z.string().trim().min(1) }).strict().optional(),
+    }).strict().describe("At least one proven publication, update or event date is required."),
+    source_url: publicUrl.describe("Exact public page (a LinkedIn post permalink, never a /in/ profile)."),
+    source_label: z.string().trim().min(1),
+    confidence: z.enum(["medium", "high"]),
+    level: z.enum(["INFO", "STRONG", "CRITICAL", "GOLDEN"]),
+    commercial_evidence: z.string().trim().min(1).optional().describe("Required for STRONG, CRITICAL and GOLDEN."),
+    commercial_pressure_type: z.enum([
+        "EXPLICIT_PROBLEM_OR_RISK", "EXPLICIT_DEADLINE_OR_MANDATE", "ACTIVE_PROCUREMENT_OR_EVALUATION", "ACTIVE_CONTACT_WINDOW",
+        "INCIDENT_OR_ENFORCEMENT", "CONTRACT_RENEWAL_OR_REPLACEMENT", "VERIFIED_OPERATIONAL_BOTTLENECK", "REGULATORY_CLEARANCE_OR_CERTIFICATION",
+    ]).optional().describe("Required for STRONG, CRITICAL and GOLDEN. GOLDEN needs DIRECT_INTENT, ACTIVE_CONTACT_WINDOW or ACTIVE_PROCUREMENT_OR_EVALUATION."),
+}).strict();
+const provenDate = z.object({ date: day, evidence: z.string().trim().min(12).max(2_000) }).strict();
+const eventRef = z.object({
+    event_id: id.optional().describe("An event already read from the history. Never combined with creation fields."),
+    name: z.string().trim().min(1).max(300).optional().describe("Event name without the year. Required without event_id."),
+    edition: z.string().trim().min(1).max(200).optional().describe("Edition year alone, e.g. 2026. Required without event_id."),
+    starts_on: provenDate.optional().describe("Required without event_id."),
+    ends_on: provenDate.optional(),
+    city: z.string().trim().min(1).max(500).nullable().optional(),
+    country_code: z.string().trim().regex(/^[A-Za-z]{2}$/).nullable().optional().describe("ISO-2."),
+    venue: z.string().trim().min(1).max(500).nullable().optional(),
+    official_url: publicUrl.nullable().optional(),
+    event_type: z.enum(["WEBINAR", "CONGRESS", "TRADE_SHOW", "OTHER"]).optional(),
+    not_duplicate_of: z.array(id).max(20).optional().describe("Only after a QUALIFY_EVENT_AMBIGUOUS refusal: candidate ids the source proves are different events."),
+}).strict();
+const participation = z.object({
+    roles: z.array(z.enum(["EXHIBITOR", "SPONSOR", "SPEAKER", "PARTNER", "ORGANIZER", "CONTRIBUTOR", "PARTICIPANT", "UNKNOWN", "OTHER", "REGISTERED", "ATTENDED", "INVITED"])).min(1).max(20)
+        .describe("PERSON target: REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER, OTHER. COMPANY target: all except REGISTERED/ATTENDED/INVITED. A registration never proves attendance."),
+    role_details: z.array(z.string().trim().min(1).max(500)).max(50).default([]),
+    stands: z.array(z.string().trim().min(1).max(200)).max(50).default([]),
+    source_urls: z.array(publicUrl.max(2_048)).max(50).default([]).describe("Required unless client_document proves the participation."),
+    client_document: z.object({
+        file_name: z.string().trim().min(1).max(300),
+        received_on: day,
+        provided_by: z.string().trim().min(1).max(300),
+    }).strict().nullable().optional().describe("Document supplied by the client (no web address)."),
+    source_provider: z.string().trim().min(1).max(500).nullable().optional(),
+    activity_summary: z.string().trim().max(5_000).nullable().optional(),
+    proof_excerpt: z.string().trim().min(1).max(20_000).optional().describe("Readable excerpt quoting the proof. Required when creating."),
+    observed_on: day,
+    verified_on: day.nullable().optional().describe("Required when status is VERIFIED; never before observed_on."),
+    status: z.enum(["UNVERIFIED", "VERIFIED", "DISPUTED", "REFUTED"]),
+    correction_reason: z.string().trim().min(1).max(5_000).optional().describe("Required when correcting (not merely corroborating) the current snapshot."),
+}).strict();
+const sourcedText = (max) => sourced(z.string().trim().min(1).max(max));
+const canonicalLocation = z.object({
+    city: z.string().trim().min(1).max(200).optional(),
+    region: z.string().trim().min(1).max(200).optional(),
+    postal_code: z.string().trim().min(1).max(200).optional(),
+    country_code: z.string().trim().regex(/^[A-Z]{2}$/),
+    street: z.string().trim().min(1).max(500).optional(),
+}).strict();
+const proposedCandidate = z.object({
+    display_name: sourcedText(300),
+    company_name: sourcedText(300).optional(),
+    first_name: sourcedText(150).optional(),
+    last_name: sourcedText(150).optional(),
+    job_title: sourcedText(300).optional(),
+    email: sourced(z.string().trim().email().max(320)).optional(),
+    linkedin_url: sourced(z.string().url()).optional().describe("A LinkedIn person URL (https://www.linkedin.com/in/...)."),
+    rpps_number: sourced(z.string().trim().regex(/^\d{11}$/)).optional().describe("11-digit RPPS, never invented."),
+    location: sourced(canonicalLocation).optional(),
+    image_url: sourced(z.string().url()).optional(),
+    provider_record: z.object({ provider: id, id, source_urls: sourceUrls }).strict().optional(),
+}).strict();
+const longSourceUrls = z.array(z.string().min(12).max(2_000).regex(/^https?:\/\/\S+$/)).min(1).max(10);
+const sourcedLong = (max) => z.object({ value: z.string().trim().min(1).max(max), source_urls: longSourceUrls }).strict();
+const discoverCandidate = z.object({
+    display_name: sourcedLong(500),
+    company_name: sourcedLong(500),
+    first_name: sourcedLong(500).optional(),
+    last_name: sourcedLong(500).optional(),
+    job_title: sourcedLong(500).optional(),
+    email: z.object({ value: z.string().min(3).max(320).regex(/^[^@\s]+@[^@\s]+\.[^@\s]+$/), source_urls: longSourceUrls }).strict().optional(),
+    linkedin_url: z.object({ value: z.string().min(12).max(500).regex(/^https?:\/\/([A-Za-z0-9-]+\.)*linkedin\.com\/in\/\S+$/), source_urls: longSourceUrls }).strict().optional(),
+    location: sourcedLong(500).optional(),
+    image_url: z.object({ value: z.string().min(12).max(2_000).regex(/^https?:\/\/\S+$/), source_urls: longSourceUrls }).strict().optional(),
+    provider_record: z.object({ provider: z.string().trim().min(1).max(200), record_id: z.string().trim().min(1).max(500), source_urls: longSourceUrls }).strict().optional(),
+}).strict();
+const employerCompany = z.object({
+    company_lead_id: id.optional().describe("Exact id of a candidate from qualification_search_employer. Never guessed from a domain or SIREN."),
+    company_name: sourcedText(500).optional(),
+    company_website: sourced(z.string().trim().url().max(2_000)).optional(),
+    finess: sourcedText(40).optional(),
+    location: sourced(z.object({
+        city: z.string().trim().min(1).max(200).optional(), postal_code: z.string().trim().min(1).max(40).optional(),
+        region: z.string().trim().min(1).max(200).optional(), country_code: z.string().trim().min(2).max(3).optional(),
+        street: z.string().trim().min(1).max(500).optional(),
+    }).strict()).optional(),
+    legal_identity: z.object({
+        legal_name: sourcedText(500).optional(), siren: sourcedText(40).optional(), siret: sourcedText(40).optional(),
+        foreign_registration_number: sourcedText(80).optional(), country_code: sourced(z.string().trim().min(2).max(3)).optional(),
+    }).strict().optional(),
+}).strict();
+// ---------------------------------------------------------------------------
+/** Outils qui ne font que lire : annotés readOnlyHint, utilisables sans nom d'agent. */
+export const QUALIFICATION_READ_TOOL_NAMES = [
+    "get_qualification_context", "get_qualification_document", "get_qualification_rules", "validate_qualification_section",
+    "list_qualification_versions", "get_qualification_version", "qualification_search_employer", "qualification_readback_contact_proposal",
+    "qualification_get_working_corpus", "qualification_read_history", "qualification_read_known_contacts", "qualification_read_employment_evidence",
+];
+export const QUALIFICATION_WRITE_TOOL_NAMES = [
+    "submit_qualification_patch", "restore_qualification_version", "mark_for_requalification", "qualification_write_signal", "qualification_record_event",
+    "qualification_link_employer", "qualification_propose_contacts", "qualification_finalize_contacts", "qualification_discover_contact",
+    "qualification_enrich_email", "qualification_geocode_location", "qualification_save_working_corpus",
+];
+export const QUALIFICATION_TOOL_NAMES = [...QUALIFICATION_READ_TOOL_NAMES, ...QUALIFICATION_WRITE_TOOL_NAMES];
+export function registerQualificationTools(server, client = getClient()) {
+    const post = (path, body) => client.post(`/api/qualify-lead${path}`, body);
+    const def = (name, description, shape, cb) => {
+        const readOnly = QUALIFICATION_READ_TOOL_NAMES.includes(name);
+        server.tool(name, description, shape, { readOnlyHint: readOnly, destructiveHint: false }, cb);
+    };
+    // -- Lectures ------------------------------------------------------------
+    def("get_qualification_context", "Read the qualification input for one lead: the agent input, the current qualification sheet with its authors, the business-field policy, " +
+        "readiness, and the three freshness guards (guards.expected_schema_hash, expected_lead_revision, expected_context_digest) that submit_qualification_patch requires. " +
+        "Read again before every write: the guards change after each write or schema change. Read-only.", { organization_id: org, lead_id: id, lead_group_id: id }, ({ organization_id, lead_id, lead_group_id }) => run(client, () => post("/v3/context", { organizationId: organization_id, leadId: lead_id, leadGroupId: lead_group_id })));
+    def("get_qualification_document", "Read the current qualification sheet of a lead (qualification_document, with authors and any issues), the freshness guards and readiness, " +
+        "plus the summary list of its 10 latest versions. Use get_qualification_version for one full version. Read-only.", { organization_id: org, lead_id: id, lead_group_id: id }, ({ organization_id, lead_id, lead_group_id }) => run(client, async () => {
+        const context = await post("/v3/context", { organizationId: organization_id, leadId: lead_id, leadGroupId: lead_group_id });
+        const versions = await client.get("/api/qualify-lead/v3/versions", new URLSearchParams({ organizationId: organization_id, leadId: lead_id, limit: "10" }));
+        return {
+            lead_id,
+            guards: context.guards,
+            qualification_document: context.record?.qualification_document ?? null,
+            qualification_document_issues: context.record?.qualification_document_issues ?? [],
+            readiness: context.readiness,
+            versions: versions?.versions ?? versions,
+        };
+    }));
+    def("get_qualification_rules", "Read the qualification rules as the platform's qualification agent receives them (from the platform prompt registry), for a company or a person. " +
+        "Do not improvise rules: if it fails with QUALIFICATION_RULES_UNAVAILABLE, retry later; with QUALIFICATION_RULES_NOT_CONFIGURED the platform prompt registry is not configured on this server: stop and tell the administrator, retrying will not help. Read-only.", { organization_id: org, entity: z.enum(["company", "person"]) }, ({ organization_id, entity }) => run(client, () => client.get("/api/qualify-lead/rules", new URLSearchParams({ organizationId: organization_id, entity }))));
+    def("list_qualification_versions", "List the versions of a lead's qualification sheet, most recent first (summary only, with authors). Read-only.", { organization_id: org, lead_id: id, limit: z.number().int().min(1).max(200).optional() }, ({ organization_id, lead_id, limit }) => run(client, () => {
+        const q = new URLSearchParams({ organizationId: organization_id, leadId: lead_id });
+        if (limit)
+            q.set("limit", String(limit));
+        return client.get("/api/qualify-lead/v3/versions", q);
+    }));
+    def("get_qualification_version", "Read one version of a qualification sheet in full, to compare it with the current one or before restoring it. Read-only.", { organization_id: org, submission_id: id.describe("Id of a version from list_qualification_versions.") }, ({ organization_id, submission_id }) => run(client, () => client.get(`/api/qualify-lead/v3/versions/${encodeURIComponent(submission_id)}`, new URLSearchParams({ organizationId: organization_id }))));
+    def("validate_qualification_section", "Try one section of the qualification sheet against the contract with the lead's current input and sheet. Writes nothing. " +
+        "Use it before submit_qualification_patch to fix each refused path. `patch` uses the contract's own snake_case keys and must carry entity_type: \"company\" or \"person\" (matching the lead's group).", {
+        organization_id: org, lead_id: id, lead_group_id: id,
+        section: z.string().trim().min(1).describe("A section of the write order (see the contract / get_qualification_rules)."),
+        patch: z.record(z.string(), z.unknown()).describe("The section's patch, in the contract's own keys."),
+        session_ref: sessionRef,
+    }, ({ organization_id, lead_id, lead_group_id, section, patch, session_ref }) => run(client, async () => {
+        let triggerRunId;
+        try {
+            triggerRunId = externalRunId(session_ref);
+        }
+        catch {
+            triggerRunId = undefined;
+        }
+        return post("/v3/validate-section", { organizationId: organization_id, leadId: lead_id, leadGroupId: lead_group_id, section, patch, ...(triggerRunId ? { triggerRunId } : {}) });
+    }));
+    // -- Fiche -----------------------------------------------------------------
+    def("submit_qualification_patch", "Write a patch to a lead's qualification sheet, judged by the qualification contract. dry_run defaults to TRUE: validate first, read the diff, then send dry_run=false. " +
+        "Guards (expected_schema_hash, expected_lead_revision, expected_context_digest) come unchanged from get_qualification_context; stale guards are refused and nothing is written. " +
+        "`reason` is required: one short, concrete sentence saying what changes, why and on which proof. The server stores it on the version (shown in the sheet's history) and it is part of the derived idempotency key. " +
+        "The write is refused with QUALIFICATION_RUN_IN_PROGRESS while the platform agent processes this lead. Every contract refusal returns each path to fix. " +
+        "`patch` uses the contract's own snake_case keys and must carry entity_type (\"company\" or \"person\", matching the lead's group). The MCP builds the envelope (lead_id, run_id, contract_version) and the external-agent correlation.", {
+        organization_id: org, lead_group_id: id, lead_id: id,
+        patch: z.record(z.string(), z.unknown()).describe("QualificationPatchV3, in the contract's own keys."),
+        expected_schema_hash: z.string().trim().min(1), expected_lead_revision: z.number().int().min(0), expected_context_digest: z.string().trim().min(1),
+        reason: z.string().trim().min(1).max(1_000),
+        contract_version: z.string().trim().min(1).optional().describe(`Contract version from get_qualification_context. Defaults to ${QUALIFICATION_CONTRACT_VERSION_DEFAULT}.`),
+        dry_run: dryRun, idempotency_key: idempotencyKey, session_ref: sessionRef,
+    }, (a) => run(client, async () => {
+        const correlation = externalCorrelation(a.session_ref);
+        const submission = {
+            contract_version: a.contract_version ?? QUALIFICATION_CONTRACT_VERSION_DEFAULT,
+            lead_id: a.lead_id, run_id: correlation.triggerRunId,
+            expected_schema_hash: a.expected_schema_hash, expected_lead_revision: a.expected_lead_revision,
+            expected_context_digest: a.expected_context_digest, patch: a.patch,
+        };
+        const result = await post("/v3/submit", {
+            organizationId: a.organization_id, leadGroupId: a.lead_group_id,
+            idempotencyKey: a.idempotency_key ?? derivedKey("mcp-qual", { submission, reason: a.reason }),
+            dryRun: a.dry_run, reason: a.reason, correlation, submission,
+        });
+        return result;
+    }));
+    def("restore_qualification_version", "Restore a previous version of a qualification sheet as a new write, judged by the contract. dry_run defaults to TRUE. `reason` is required and recorded by the server. " +
+        "expected_lead_revision comes from get_qualification_context. Refused with QUALIFICATION_RUN_IN_PROGRESS during an agent run.", {
+        organization_id: org, lead_group_id: id, lead_id: id, submission_id: id.describe("Version to restore (list_qualification_versions)."),
+        expected_lead_revision: z.number().int().min(0), reason: z.string().trim().min(1).max(1_000),
+        dry_run: dryRun, idempotency_key: idempotencyKey, session_ref: sessionRef,
+    }, (a) => run(client, () => post("/v3/restore", {
+        organizationId: a.organization_id, leadGroupId: a.lead_group_id, leadId: a.lead_id, submissionId: a.submission_id,
+        idempotencyKey: a.idempotency_key ?? derivedKey("mcp-restore", { l: a.lead_id, s: a.submission_id, r: a.expected_lead_revision }),
+        expectedLeadRevision: a.expected_lead_revision, reason: a.reason, dryRun: a.dry_run, correlation: externalCorrelation(a.session_ref),
+    })));
+    def("mark_for_requalification", "Mark a lead for requalification with a reason. It launches no run: the platform's scheduled pass picks it up. Refused during an agent run.", { organization_id: org, lead_id: id, reason: z.string().trim().min(1).max(1_000), session_ref: sessionRef }, (a) => run(client, () => post("/v3/requalify", { organizationId: a.organization_id, leadId: a.lead_id, reason: a.reason, correlation: externalCorrelation(a.session_ref) })));
+    // -- Signaux et événements ---------------------------------------------------
+    def("qualification_write_signal", "Write one dated, sourced signal on a lead (qualification contract). dry_run defaults to TRUE. content is exactly 3 paragraphs (dated fact, substance, commercial read). " +
+        "STRONG/CRITICAL/GOLDEN need commercial_evidence and commercial_pressure_type; a person's event participation signal is written by the product, not here.", { organization_id: org, lead_id: id, lead_group_id: id, account_id: id.optional(), signal: signalPayload, dry_run: dryRun, idempotency_key: idempotencyKey, session_ref: sessionRef }, (a) => run(client, () => {
+        const signal = camelizeKeys(a.signal);
+        return post("/signals", {
+            contractVersion: SIGNAL_CONTRACT_VERSION, organizationId: a.organization_id, leadId: a.lead_id, leadGroupId: a.lead_group_id,
+            ...(a.account_id ? { accountId: a.account_id } : {}),
+            idempotencyKey: a.idempotency_key ?? derivedKey("mcp-signal", { l: a.lead_id, signal }),
+            dryRun: a.dry_run, signal, correlation: externalCorrelation(a.session_ref),
+        });
+    }));
+    def("qualification_record_event", "Record an event and a participation (company or person) on a lead. dry_run defaults to TRUE. target defaults to COMPANY; PERSON writes on the person lead (no account_id, no witness, person roles only). " +
+        "Either event_id (known event) or name+edition+starts_on (new/matching event). A registration (REGISTERED) never proves attendance (ATTENDED).", {
+        organization_id: org, lead_id: id, lead_group_id: id, account_id: id.optional(),
+        target: z.enum(["COMPANY", "PERSON"]).optional(),
+        event: eventRef, participation,
+        witness: z.object({ person_lead_id: id, person_lead_group_id: id }).strict().optional().describe("COMPANY target only: a person whose presence is proven."),
+        dry_run: dryRun, idempotency_key: idempotencyKey, session_ref: sessionRef,
+    }, (a) => run(client, () => {
+        const body = camelizeKeys({ event: a.event, participation: a.participation, ...(a.witness ? { witness: a.witness } : {}) });
+        return post("/events", {
+            contractVersion: EVENT_CONTRACT_VERSION, ...(a.target ? { target: a.target } : {}),
+            organizationId: a.organization_id, leadId: a.lead_id, leadGroupId: a.lead_group_id,
+            ...(a.account_id ? { accountId: a.account_id } : {}),
+            idempotencyKey: a.idempotency_key ?? derivedKey("mcp-event", { l: a.lead_id, t: a.target, body }),
+            dryRun: a.dry_run, ...body, correlation: externalCorrelation(a.session_ref),
+        });
+    }));
+    // -- Employeur -------------------------------------------------------------
+    def("qualification_search_employer", "Search the organization's company leads for a person's employer. Returns candidates and a searchReceipt to copy unchanged into qualification_link_employer (valid 30 minutes). " +
+        "A search with totalCandidates=0 is what allows creating the company. Read-only.", {
+        organization_id: org, person_lead_id: id, person_lead_group_id: id,
+        query: z.object({ company_name: z.string().trim().min(1).max(500), city: z.string().trim().min(1).max(200).optional(),
+            finess: z.string().trim().min(1).max(40).optional(), siren: z.string().trim().min(1).max(40).optional() }).strict(),
+        after_company_lead_id: id.optional().describe("nextAfterCompanyLeadId of the previous page; keep the same criteria."),
+        session_ref: sessionRef,
+    }, (a) => run(client, () => post("/employer/search", {
+        contractVersion: EMPLOYER_CONTRACT_VERSION, organizationId: a.organization_id, personLeadId: a.person_lead_id, personLeadGroupId: a.person_lead_group_id,
+        query: camelizeKeys(a.query), ...(a.after_company_lead_id ? { afterCompanyLeadId: a.after_company_lead_id } : {}),
+        correlation: readCorrelation(a.session_ref),
+    })));
+    def("qualification_link_employer", "Attach a person to their employer company (an existing candidate by company_lead_id, or a new company), with evidence. Needs the search_receipt from qualification_search_employer. " +
+        "Closes previous employments unless close_previous_employment=false (a proven cumulative job only). Refused during an agent run.", {
+        organization_id: org, person_lead_id: id, person_lead_group_id: id, company: employerCompany,
+        search_receipt: z.string().min(1).max(64_000).describe("Copied unchanged from qualification_search_employer."),
+        evidence: z.object({
+            provider: z.string().trim().min(1).max(120), source_url: publicUrl, excerpt: z.string().trim().min(1).max(20_000),
+            observed_at: z.string().datetime({ offset: true }).describe("ISO 8601 with timezone."), verified_at: z.string().datetime({ offset: true }).describe("ISO 8601 with timezone, never before observed_at."),
+        }).strict(),
+        close_previous_employment: z.boolean().default(true), reason: z.string().trim().min(1).max(2_000),
+        idempotency_key: idempotencyKey, session_ref: sessionRef,
+    }, (a) => run(client, () => {
+        const company = camelizeKeys(a.company);
+        const evidence = camelizeKeys(a.evidence);
+        return post("/employer", {
+            contractVersion: EMPLOYER_CONTRACT_VERSION, organizationId: a.organization_id, personLeadId: a.person_lead_id, personLeadGroupId: a.person_lead_group_id,
+            company, searchReceipt: a.search_receipt, evidence, closePreviousEmployment: a.close_previous_employment, reason: a.reason,
+            idempotencyKey: a.idempotency_key ?? derivedKey("mcp-employer", { p: a.person_lead_id, company, evidence, c: a.close_previous_employment }),
+            correlation: externalCorrelation(a.session_ref),
+        });
+    }));
+    // -- Contacts découverts -----------------------------------------------------
+    def("qualification_propose_contacts", "Propose one discovered contact (a person found while qualifying a lead) for the lead's person group. dry_run defaults to TRUE. " +
+        "Every value carries its public source_urls. Check qualification_read_known_contacts first to avoid duplicates. Call once per candidate, then qualification_finalize_contacts.", { organization_id: org, source_lead_id: id, lead_group_id: id, candidate: proposedCandidate, dry_run: dryRun, idempotency_key: idempotencyKey, session_ref: sessionRef }, (a) => run(client, () => {
+        const candidate = camelizeKeys(a.candidate);
+        return post("/discovered-contacts/propose", {
+            contractVersion: CONTACT_CONTRACT_VERSION, organizationId: a.organization_id, sourceLeadId: a.source_lead_id, leadGroupId: a.lead_group_id,
+            idempotencyKey: a.idempotency_key ?? derivedKey("mcp-contact", { s: a.source_lead_id, candidate }),
+            dryRun: a.dry_run, candidate, correlation: externalCorrelationWithoutMission(a.session_ref),
+        });
+    }));
+    def("qualification_finalize_contacts", "Finalize the contacts proposed in this session (same session_ref) for a lead: creates the person leads. With readback_only=true it only reads the state of that finalization (ready, complete, per-proposal outcome) and writes nothing. " +
+        "Refused during an agent run.", { organization_id: org, source_lead_id: id, lead_group_id: id, account_run_id: id.optional(), readback_only: z.boolean().default(false), session_ref: sessionRef }, (a) => run(client, () => post(a.readback_only ? "/discovered-contacts/finalization-readback" : "/discovered-contacts/finalize", {
+        contractVersion: CONTACT_CONTRACT_VERSION, organizationId: a.organization_id, sourceLeadId: a.source_lead_id, leadGroupId: a.lead_group_id,
+        sourceTriggerRunId: externalRunId(a.session_ref), ...(a.account_run_id ? { accountRunId: a.account_run_id } : {}),
+    })));
+    def("qualification_readback_contact_proposal", "Read back one proposed contact by proposal_id (as returned by qualification_propose_contacts). Read-only.", { organization_id: org, proposal_id: id }, (a) => run(client, () => post("/discovered-contacts/readback", { organizationId: a.organization_id, proposalId: a.proposal_id })));
+    def("qualification_discover_contact", "Propose a discovered contact for a COMPANY lead through the discovery route, with the persona-eligibility decision and the candidates screened out. dry_run defaults to TRUE. " +
+        "screened_out must be non-empty unless no_other_person_found=true (and then it must be empty).", {
+        organization_id: org, lead_group_id: id, lead_id: id, candidate: discoverCandidate,
+        persona_eligibility: z.object({ decision: z.literal("eligible"), reason: z.string().trim().min(1).max(1_000), source_urls: longSourceUrls }).strict(),
+        screened_out: z.array(z.object({
+            label: z.string().trim().min(1).max(500).optional(),
+            reason: z.enum(["same_as_subject", "not_same_company", "not_relevant", "identity_ambiguous", "insufficient_current_evidence", "search_noise"]),
+            source_urls: longSourceUrls,
+        }).strict()).optional(),
+        no_other_person_found: z.boolean().optional(),
+        dry_run: dryRun, idempotency_key: idempotencyKey, session_ref: sessionRef,
+    }, (a) => run(client, () => {
+        const rest = camelizeKeys({ candidate: a.candidate, persona_eligibility: a.persona_eligibility, screened_out: a.screened_out, no_other_person_found: a.no_other_person_found });
+        return post("/discover-contact", {
+            contractVersion: CONTACT_CONTRACT_VERSION, organizationId: a.organization_id, leadGroupId: a.lead_group_id, leadId: a.lead_id,
+            idempotencyKey: a.idempotency_key ?? derivedKey("mcp-discover", { l: a.lead_id, rest }),
+            dryRun: a.dry_run, ...rest, correlation: externalCorrelation(a.session_ref),
+        });
+    }));
+    // -- Enrichissements ---------------------------------------------------------
+    def("qualification_enrich_email", "Look up a person's professional email (provider enrichment) after their qualification sheet is persisted. Writes the email when found. Uses the session id as the run id.", { organization_id: org, lead_id: id, lead_group_id: id, qualification_submission_id: id.optional(), session_ref: sessionRef }, (a) => run(client, () => {
+        const runId = externalRunId(a.session_ref);
+        return post("/email-enrichment", {
+            contractVersion: "1.0.0", organizationId: a.organization_id, leadId: a.lead_id, leadGroupId: a.lead_group_id,
+            ...(a.qualification_submission_id ? { qualificationSubmissionId: a.qualification_submission_id } : {}),
+            qualificationTriggerRunId: runId, traceId: runId,
+        });
+    }));
+    def("qualification_geocode_location", "Geocode a lead's canonical location after it changed. Pass requested_source_location_hash (sha256:...) to refuse if the location changed meanwhile.", {
+        organization_id: org, lead_id: id, lead_group_id: id,
+        requested_source_location_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+        reason: z.enum(["qualification_location_changed", "manual_location_changed", "backfill"]).default("qualification_location_changed"),
+        session_ref: sessionRef,
+    }, (a) => run(client, async () => {
+        externalRunId(a.session_ref); // refuse without an agent name, like every write
+        return post("/location-geocode", {
+            contractVersion: LOCATION_CONTRACT_VERSION, organizationId: a.organization_id, leadId: a.lead_id, leadGroupId: a.lead_group_id,
+            ...(a.requested_source_location_hash ? { requestedSourceLocationHash: a.requested_source_location_hash } : {}), reason: a.reason,
+        });
+    }));
+    // -- Corpus de travail -------------------------------------------------------
+    def("qualification_get_working_corpus", "Read the frozen working corpus (research text) saved for a company lead. Answers WORKING_CORPUS_NOT_STORED (404) when none was saved. Read-only.", { organization_id: org, company_lead_id: id }, (a) => run(client, () => client.get("/api/qualify-lead/working-corpus", new URLSearchParams({ organizationId: a.organization_id, companyLeadId: a.company_lead_id }))));
+    def("qualification_save_working_corpus", "Save the frozen working corpus of a company lead (up to 12000 characters), so the people of that company are qualified from the same research.", { organization_id: org, company_lead_id: id, text: z.string().min(1).max(12_000), frozen_at: z.string().datetime({ offset: true }).optional().describe("ISO 8601; defaults to now."), session_ref: sessionRef }, (a) => run(client, () => client.put("/api/qualify-lead/working-corpus", {
+        contractVersion: WORKING_CORPUS_CONTRACT_VERSION, organizationId: a.organization_id, companyLeadId: a.company_lead_id, text: a.text,
+        triggerRunId: externalRunId(a.session_ref), frozenAt: a.frozen_at ?? new Date().toISOString(),
+    })));
+    // -- Lectures de recherche ---------------------------------------------------
+    def("qualification_read_history", "Read the lead's qualification history (past submissions, signals, events). Read-only.", { organization_id: org, lead_id: id, lead_group_id: id, limit: z.number().int().min(1).max(50).default(20), force: z.boolean().default(false).describe("Bypass the freshness gates, as the platform input does.") }, (a) => run(client, () => post("/history", { organizationId: a.organization_id, leadId: a.lead_id, leadGroupId: a.lead_group_id, limit: a.limit, force: a.force })));
+    def("qualification_read_known_contacts", "Check up to 30 candidate contacts against the people already in the lead group (by email, LinkedIn, RPPS, name) before proposing them. Writes nothing.", {
+        organization_id: org, source_lead_id: id, lead_group_id: id,
+        candidates: z.array(z.object({
+            display_name: z.string().trim().min(1).max(300), first_name: z.string().trim().min(1).max(150).optional(), last_name: z.string().trim().min(1).max(150).optional(),
+            email: z.string().trim().min(3).max(320).optional(), linkedin_url: z.string().trim().min(1).max(2_048).optional(),
+            rpps_number: z.string().trim().regex(/^\d{11}$/).optional(),
+        }).strict()).min(1).max(30),
+        session_ref: sessionRef,
+    }, (a) => run(client, () => post("/known-contacts", {
+        contractVersion: CONTACT_CONTRACT_VERSION, organizationId: a.organization_id, sourceLeadId: a.source_lead_id, leadGroupId: a.lead_group_id,
+        candidates: camelizeKeys(a.candidates),
+        correlation: readCorrelation(a.session_ref),
+    })));
+    def("qualification_read_employment_evidence", "Read the evidence behind one employment relationship of a person lead, 5 items at most per page; pass the returned cursor for the next page. Read-only.", { organization_id: org, lead_id: id, lead_group_id: id, relationship_id: id, cursor: id.optional(), limit: z.number().int().min(1).max(5).default(5) }, (a) => run(client, () => post("/employment-evidence", {
+        organizationId: a.organization_id, leadId: a.lead_id, leadGroupId: a.lead_group_id, relationshipId: a.relationship_id,
+        ...(a.cursor ? { cursor: a.cursor } : {}), limit: a.limit,
+    })));
+}

package/dist/tools/signals.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
+import { externalAgentName } from "../correlation.js";
 import { toolResult, toolError, handleToolError } from "../types.js";
 // Anti-loop guardrail, NOT a business limit: bounds how many signal mutations
 // a single server run (= one agent session) can perform.
@@ -97,7 +98,8 @@ export function registerSignalTools(server) {
                 .string()
                 .optional()
                 .describe("Technical identifier of the producing agent, 3-4 words max, kebab-case or " +
-                "space-separated (e.g. 'leadify qualification', 'budget-monitor')."),
+                "space-separated (e.g. 'leadify qualification', 'budget-monitor'). Ignored when the MCP runs as an external agent " +
+                "(LEADIFY_EXTERNAL_AGENT_NAME): the signal is then signed external-agent:<name>."),
             source_url: z.string().url().optional().describe("URL of the original source."),
             reason: reasonParam,
         },
@@ -126,7 +128,11 @@ export function registerSignalTools(server) {
                 body.dateEvidence = date_evidence;
             if (source !== undefined)
                 body.source = source;
-            if (agent_source !== undefined)
+            // PRD-2831 : un agent externe (Louise) signe ses signaux de son nom, quel que soit agent_source.
+            const externalName = externalAgentName();
+            if (externalName)
+                body.agentSource = `external-agent:${externalName}`;
+            else if (agent_source !== undefined)
                 body.agentSource = agent_source;
             if (source_url !== undefined)
                 body.sourceUrl = source_url;

package/package.json

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