@agifyai/leadify-mcp 9.6.0 → 9.7.1

package/README.md

@@ -195,8 +195,12 @@ Conséquences pratiques :
 
 ## Sémantique des événements
 
-Une participation est rattachée à l’entreprise canonique (`Account`), même
-lorsqu’un `lead_id` est fourni au tool. `get_leads.event_filter` et
+Une participation porte sur une entreprise ou sur une personne (PRD-2475,
+serveur PRD-2473). Un `account_id` ou le `lead_id` d’un prospect Entreprise
+écrit, comme avant, sur l’entreprise canonique (`Account`). Le `lead_id` d’un
+prospect Personne, ou un `person_id` (`canonicalIdentity.id` d’un prospect Personne, `kind: PERSON`), écrit une
+participation propre à la personne canonique : elle la suit dans tous ses
+groupes. Les outils d’events d’entreprise fonctionnent comme avant. `get_leads.event_filter` et
 `list_event_participations` ajoutent explicitement `VERIFIED` lorsque le statut
 n’est pas fourni. Pour relire des faits `UNVERIFIED`, `DISPUTED` ou `REFUTED`,
 l’agent doit demander ces statuts explicitement. Une donnée incertaine ou
@@ -211,6 +215,31 @@ des sélecteurs courants sans effacer son historique. Les champs legacy
 restent disponibles pour compatibilité/export, mais ne sont jamais synchronisés
 depuis ce modèle.
 
+Événements d’une personne :
+
+- Rôles d’une personne : `REGISTERED` (inscrit), `ATTENDED` (présent),
+  `INVITED` (invité), `SPEAKER`, `ORGANIZER`, `OTHER`. Les trois premiers sont
+  refusés pour une entreprise. Inscrit, présent et invité sont trois faits
+  distincts : une inscription ne prouve jamais une présence.
+- Une liste d’inscrits fournie par le client est une preuve valable de
+  l’inscription, y compris pour une personne désinscrite ensuite ou inscrite
+  plusieurs fois : rôle `REGISTERED` et `client_document { file_name,
+  received_on, provided_by }`, sans adresse web. `VERIFIED` exige une adresse
+  web ou un `client_document`.
+- Un event de l’employeur n’est jamais une participation de la personne. Lue
+  avec le `lead_id` d’une personne, `list_event_participations` rend ses
+  participations propres (`origin: PERSON`) puis celles de son employeur
+  (`origin: EMPLOYER`). Sans `target`, `person_ids` ni `lead_id` de personne,
+  la liste ne rend que les entreprises, comme avant ; `target: PERSON` ou
+  `person_ids` lisent les personnes.
+- `get_leads.event_filter.subject` vaut `EMPLOYER` (défaut, comportement
+  historique) ou `PERSON` (seules les personnes qui portent elles-mêmes la
+  participation, par exemple les inscrits d’un webinar).
+- Les events ont un type facultatif `event_type` : `WEBINAR`, `CONGRESS`,
+  `TRADE_SHOW`, `OTHER` (filtre `event_types` dans `list_events`).
+  `get_event` rend `participationCounts { companies, persons }`.
+- L’absence d’enregistrement ne prouve rien.
+
 Il n’existe plus de score de confiance événementiel : le statut et ses preuves
 portent seuls la validation utile. `Event.description` explique l’audience et
 l’utilité de l’événement ; `activity_summary` explique ce que l’entreprise y
@@ -244,17 +273,17 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `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. |
-| `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter`. |
+| `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. |
 | `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 ; les événements archivés sont masqués par défaut. |
-| `get_event` | Lire un événement partagé et son état d’archivage. |
-| `create_event` | Créer un événement partagé avec une clé d’idempotence. |
-| `update_event` | Modifier ou archiver sans suppression un événement partagé, avec version attendue. |
-| `list_event_participations` | Lister les participations d’entreprise ; filtre explicitement `VERIFIED` par défaut. |
-| `get_event_participation` | Lire un snapshot courant et son historique ; `VERIFIED` par défaut, statut incertain à demander explicitement. |
-| `record_event_participations` | Valider à blanc ou enregistrer un lot idempotent de 1 à 100 observations/corrections. |
+| `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. |
+| `create_event` | Créer un événement partagé, avec son type facultatif, et une clé d’idempotence. |
+| `update_event` | Modifier (dont le type) ou archiver sans suppression un événement partagé, avec version attendue. |
+| `list_event_participations` | Lister les participations d’entreprise et de personne, avec leur provenance ; filtres `target`, `person_ids` ; `VERIFIED` par défaut. |
+| `get_event_participation` | Lire un snapshot courant d’entreprise ou de personne et son historique ; `VERIFIED` par défaut, statut incertain à demander explicitement. |
+| `record_event_participations` | Valider à blanc ou enregistrer un lot idempotent de 1 à 100 observations/corrections d’entreprise ou de personne (inscrit, présent, invité, preuve « document du client »). |
 | `preview_reset_sequence_messages` / `execute_reset_sequence_messages` | Prévisualiser puis effacer irréversiblement les messages générés d'un prospect, d'une liste explicite ou d'un groupe explicite. L'exécution exige le digest de preview et une clé d'idempotence. |
 | `preview_reset_ai_fields` / `execute_reset_ai_fields` | Prévisualiser puis effacer irréversiblement les champs IA d'un prospect, d'une liste explicite ou d'un groupe explicite, sans toucher aux contacts, flags manuels, activités ou campagnes. |
 | `delete_leads` | Supprimer définitivement des leads par leurs IDs. |
@@ -468,3 +497,149 @@ préparent ni n’envoient de message commercial.
 Pour les essais locaux, `LEADIFY_LOCAL_API_URL=http://localhost:<port>` dirige
 le MCP vers une origine HTTP locale. Les adresses distantes sont refusées par ce
 réglage ; sans ce réglage, l’adresse habituelle de Leadify est utilisée.
+
+## Prospection autonome : contrat MCP `leadify-outreach-mcp.v1`
+
+Ces outils déposent des décisions fraîches dans Leadify. Louise écrit la décision du
+moment pour une personne, avec au plus un message Gmail et un message ou une
+invitation LinkedIn. Aucune séquence ni étape future. Le MCP ne contacte jamais
+Gmail ou Unipile pour envoyer : Leadify contrôle et exécute les dépôts acceptés.
+
+`get_mcp_runtime_info` annonce les 16 capacités du paquet et les versions serveur
+attendues. `probe_outreach: true` vérifie en plus le contrat des programmes dans
+l'organisation choisie, sans lire de prospect. `PROGRAM_CONTRACT_VERIFIED` ne
+prouve ni les autres routes ni une autorisation commerciale. Chaque réponse
+versionnée est vérifiée ; une ancienne route absente et un contrat incompatible
+produisent des erreurs distinctes des refus de droits.
+
+Chaque appel exige `organization_id`. Leadify vérifie la portée de la clé
+(organisations autorisées, y compris futures si cette portée est configurée), puis
+les autorisations propres aux comptes expéditeurs. Aucune restriction de groupe
+supplémentaire n'est ajoutée à la clé. Le programme fixe les groupes utilisables.
+Les outils ne peuvent pas autoriser un programme, relever un plafond, choisir un
+expéditeur, s'accorder un droit ou reprendre une intervention humaine.
+
+Dans la matrice, A signifie `/api/agent-outreach/programs/:programId` et C signifie
+`/api/agent-outreach-context/programs/:programId`. L'organisation figure toujours
+dans la query `organizationId`, y compris pour POST. R signifie lecture avec
+portée organisation et autorisation du compte expéditeur ; W ajoute écriture.
+Les tests de contrat et de transport sont dans `test/agent-outreach.test.mjs` ;
+`test/auth.test.mjs` vérifie le diagnostic de compatibilité.
+
+| Capacité | Outil | Permission | Route | Vérification |
+|---|---|---|---|---|
+| Programmes accessibles | `list_outreach_programs` | R | GET /api/agent-outreach/programs | version, organisation, pagination |
+| Règles et comptes | `get_outreach_program_context` | R | GET A | contexte, sans pouvoir administratif |
+| Sélection avant pagination | `query_outreach_prospects` | R | POST A/prospects/query | filtres complets, pages, erreurs |
+| Résumé d'une personne | `get_outreach_prospect_summary` | R | GET A/prospects/:leadId | identité explicite |
+| Historique des contacts | `get_outreach_contact_history` | R | GET A/contacts/:leadId | comptes accessibles, couverture |
+| Contexte frais de rédaction | `get_outreach_prospect_context` | R | GET C/people/:leadId/context | contrat, versions, état prêt ou attente |
+| Fil exact | `get_outreach_thread` | R | GET C/people/:leadId/thread | account_key, thread_id, curseur |
+| Décisions présentes | `submit_outreach_messages` | W | POST A/messages/batch | schéma, texte intact, reprises, lot partiel |
+| Messages de cette clé | `list_outreach_messages` | read + organisation | GET A/messages | pagination, projection sûre |
+| Détail et tentatives | `get_outreach_message` | read + organisation | GET A/messages/:messageId | reçu, preuve fournisseur sans enveloppe brute |
+| Annulation avant départ | `cancel_outreach_message` | read/write + organisation | POST A/messages/:messageId/cancel | révision attendue, TOO_LATE |
+| Événements à traiter | `list_outreach_events` | R | GET C/changes | curseurs, lecture sans acquittement |
+| Résultat du traitement | `acknowledge_outreach_events` | W | POST C/changes/acknowledge | préfixe complet, reprise exacte |
+| Santé de réception | `get_outreach_reception_health` | R | GET A/reception-health | couverture depuis l'inscription |
+| Conversations reçues | `list_outreach_conversations` | R | GET A/conversations | personne facultative, pagination |
+| Messages et prise en main | `get_outreach_conversation` | R | GET A/conversations/:conversationId | curseur décimal, contrôle humain en lecture |
+
+Les reçus et messages d'une clé restent consultables après retrait de son
+autorisation sur un expéditeur, tant que la clé et sa portée organisation restent
+valides. La réception est soumise aux autorisations d'expéditeurs ; elle reste
+consultable quand la distribution des envois est arrêtée. Ne pas confondre ces
+lectures avec un droit de reprendre la prospection.
+
+### Recherche et contexte
+
+Pour une relance après sept jours :
+
+```json
+{"organization_id":"org-fictive","program_id":"programme-fictif","recipe":"followup_due","limit":25}
+```
+
+Pour une recherche au 12 octobre 2026 à 12:00 UTC, après 72 heures sans message
+sortant confirmé, sans action en attente ni réponse à traiter :
+
+```json
+{
+  "organization_id":"org-fictive","program_id":"programme-fictif",
+  "filters":{
+    "last_confirmed_outbound_before":{"channel":"any","before":"2026-10-09T12:00:00Z"},
+    "pending":false,"unknown":false,"reply":"WAITING","excluded":false
+  },
+  "limit":25
+}
+```
+
+La recette `channel_gap` cherche au moins deux messages LinkedIn et zéro message
+Gmail confirmé, sans message Gmail en attente ou inconnu. Les invitations sont
+comptées séparément. `replies_to_handle` sélectionne les réponses à traiter dans
+leur propre fil. `filters.signal_filter` accepte `detected_since`,
+`detected_before`, `levels` (`STRONG`, `GOLDEN`, `CRITICAL`) et `scope`
+(`PERSON`, `COMPANY`, `BOTH`). L'absence d'historique connu n'est pas la preuve
+qu'une personne n'a jamais été contactée.
+
+La sélection expire après dix minutes. Passer son `nextCursor` dans `cursor` avec
+les mêmes filtres, recette et limite. Un curseur expiré, modifié ou lié à d'autres
+droits est refusé ; aucun redémarrage caché n'a lieu. Programmes, messages et
+conversations utilisent `after_id` pour leur page suivante. Les événements et les
+fils utilisent `cursor`. Les curseurs sont opaques et ne doivent pas être inventés.
+
+`get_outreach_prospect_summary` est un résumé. Avant d'écrire, lire
+`get_outreach_prospect_context`, vérifier `readiness.ready`, puis les fils exacts
+nécessaires avec `get_outreach_thread`. Un corps indisponible ou un simple extrait
+ne vaut pas une conversation complète. Le contexte n'effectue aucune qualification.
+
+### Dépôt et reprise
+
+`submit_outreach_messages` accepte `decisions` (1 à 20). Chaque décision contient
+`request_key`, `lead_id`, `person_id`, `purpose` (`FIRST_CONTACT`, `FOLLOW_UP`,
+`REPLY`), `reason`, `sources` (label et url), `authorization_revision`, `context`
+et `messages` (1 à 2, un par canal).
+
+Le contexte transmis comporte `contract_version: "agent-writing-context.v1"`,
+`context_version`, `facts_version`, `read_at` et l'objet `versions` exact reçu du
+serveur. Les clés de cet objet restent inchangées, dont `contactState`. Un message
+contient `channel`, `action`, `sender_id`, `account_key`, `recipient`, `subject`,
+`body`, `thread_id`, `expected_inbound_id`, `technical_parts` (signature et
+unsubscribe). Les champs nullables doivent être présents. Une réponse désigne
+son fil et son message reçu. Gmail exige un sujet ; LinkedIn exige un sujet null
+et des parties techniques vides. Le texte écrit est transmis sans modification.
+
+Reprendre un appel interrompu avec **la même request_key et le même contenu**.
+Une clé réutilisée avec un contenu différent est refusée. Chaque reçu du lot doit
+être examiné : `ACCEPTED` signifie enregistré, pas envoyé ; `WAIT` et `REFUSED`
+conservent leurs raisons. Un message `UNKNOWN` doit être réconcilié depuis les
+preuves fournisseur ; ne jamais le redéposer comme une nouvelle tentative.
+`cancel_outreach_message` demande la dernière `expected_revision` ; `TOO_LATE`
+signifie que l'annulation n'a pas eu lieu.
+
+Le journal `list_outreach_events` renvoie `changes`, `cursor`, `nextCursor` et
+`processedCursor`. Lire ne marque rien comme traité. Après traitement de chaque
+changement du préfixe, `acknowledge_outreach_events` reçoit le `cursor` et les
+`receipts` (change_id, status PROCESSED/DISMISSED, reason). Une reprise exige les
+mêmes résultats. Ce journal est distinct de l'historique administratif.
+
+### Catalogue conservé et preuve locale
+
+Les 141 outils de la version 9.7.0 restent disponibles : fiches et groupes,
+dossiers, Company/Person/emplois, signaux, exclusions, Context Workspace et
+lectures commerciales (`email_read_thread`, `linkedin_read_conversation`,
+`unipile_read_messages`, `leadify_read_activity_feed`, `get_commercial_truth`).
+`test/catalogue-9.7.0.json` vérifie leur conservation exacte dans une vraie
+réponse `tools/list`. Les outils de campagne et de qualification existants ne
+font pas partie du parcours autonome et ne sont pas appelés par ces nouveaux outils.
+
+Pour tester le MCP avec Leadify local, lancer serveur et web avec les données
+fictives du projet, puis démarrer un nouveau processus MCP avec
+`LEADIFY_LOCAL_API_URL=http://127.0.0.1:<port>` et une clé locale fictive.
+Sans cette variable, le client vise l'API publique : ne pas utiliser une vraie clé
+pour la recette. `npm test` couvre les schémas, erreurs, projections et un client
+MCP stdio relié à un serveur HTTP simulé local ; cela ne remplace pas la recette
+avec l'application, ses écritures enregistrées et sa vérification visuelle.
+
+La publication suit `publish.yml` après fusion : registre npm, archive de version
+explicite et découverte dans un processus neuf doivent être vérifiés séparément.
+Une conversation Louise déjà ouverte peut conserver un ancien catalogue.

package/dist/server.js

@@ -1,3 +1,4 @@
+import { registerAgentOutreachTools } from "./tools/agent_outreach.js";
 import { registerQualificationRunTools } from "./tools/qualification_runs.js";
 import { registerOutreachExclusionTools } from "./tools/outreach_exclusion.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -33,6 +34,7 @@ export function createServer() {
         version: MCP_VERSION,
     });
     registerAuthTools(server);
+    registerAgentOutreachTools(server);
     registerOrganizationTools(server);
     registerLeadGroupTools(server);
     registerLeadGroupFolderTools(server);

package/dist/tools/agent_outreach.d.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type LeadifyClient } from "../client.js";
+import { type ToolResult } from "../types.js";
+export declare const OUTREACH_MCP_CONTRACT = "leadify-outreach-mcp.v1";
+export declare const OUTREACH_TOOL_NAMES: readonly ["list_outreach_programs", "get_outreach_program_context", "query_outreach_prospects", "get_outreach_prospect_summary", "get_outreach_contact_history", "get_outreach_prospect_context", "get_outreach_thread", "submit_outreach_messages", "list_outreach_messages", "get_outreach_message", "cancel_outreach_message", "list_outreach_events", "acknowledge_outreach_events", "get_outreach_reception_health", "list_outreach_conversations", "get_outreach_conversation"];
+export declare const OUTREACH_SERVER_CONTRACTS: {
+    readonly program: "1.0.0";
+    readonly selection: "1.0.0";
+    readonly context: "agent-writing-context.v1";
+    readonly receipt: "agent-message-receipt.v1";
+    readonly journal: "1.0.0";
+};
+type Client = Pick<LeadifyClient, "get" | "post">;
+export declare function outreachError(error: unknown): ToolResult;
+export declare function requireOutreachVersion(data: unknown, expected: string): unknown;
+/** Provider envelopes/MIME and context snapshots are not evidence needed by the caller. */
+export declare function projectOutreachMessage(data: unknown): Record<string, unknown>;
+export declare function registerAgentOutreachTools(server: McpServer, client?: Client): void;
+export {};

package/dist/tools/agent_outreach.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { LeadifyApiError, toolResult, toolError, handleToolError } from "../types.js";
+import { identifier, scope, querySchema, queryBody, submitSchema, decisionBody, acknowledgeSchema } from "./agent_outreach_schemas.js";
+export const OUTREACH_MCP_CONTRACT = "leadify-outreach-mcp.v1";
+export const OUTREACH_TOOL_NAMES = ["list_outreach_programs", "get_outreach_program_context", "query_outreach_prospects",
+    "get_outreach_prospect_summary", "get_outreach_contact_history", "get_outreach_prospect_context", "get_outreach_thread",
+    "submit_outreach_messages", "list_outreach_messages", "get_outreach_message", "cancel_outreach_message", "list_outreach_events",
+    "acknowledge_outreach_events", "get_outreach_reception_health", "list_outreach_conversations", "get_outreach_conversation"];
+export const OUTREACH_SERVER_CONTRACTS = { program: "1.0.0", selection: "1.0.0", context: "agent-writing-context.v1", receipt: "agent-message-receipt.v1", journal: "1.0.0" };
+const object = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
+const pick = (v, keys) => Object.fromEntries(keys.filter(k => k in object(v)).map(k => [k, object(v)[k]]));
+const encoded = encodeURIComponent;
+const programPath = (id, context = false) => `/api/agent-outreach${context ? "-context" : ""}/programs/${encoded(id)}`;
+function params(org, extra = {}) {
+    return new URLSearchParams(Object.entries({ organizationId: org, ...extra }).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)]));
+}
+const postPath = (path, org) => `${path}?${params(org)}`;
+const readNotice = " Explicit organization required; access is checked by Leadify against the key's organization scope and sender grants. Discovery grants no administrative authority. No qualification launch, campaign change or direct provider send.";
+const receiptNotice = " ACCEPTED means stored, not sent. UNKNOWN must be reconciled, never retried as a new send.";
+export function outreachError(error) {
+    if (error instanceof z.ZodError)
+        return toolError("Vérifiez les paramètres de prospection.", { code: "INVALID_INPUT", issues: error.issues });
+    if (error instanceof LeadifyApiError) {
+        const code = object(error.responseBody).code;
+        if ((error.statusCode === 404 && !code) || code === "HUMAN_AUTHORITY_REQUIRED") {
+            return toolError("Cette version de Leadify ne propose pas cet outil de prospection. Vérifiez la version du serveur.", { code: "OUTREACH_TOOL_UNAVAILABLE", statusCode: error.statusCode });
+        }
+    }
+    return handleToolError(error);
+}
+export function requireOutreachVersion(data, expected) {
+    if (object(data).contractVersion !== expected)
+        throw new LeadifyApiError(409, { code: "OUTREACH_CONTRACT_INCOMPATIBLE",
+            error: "Le contrat de prospection du serveur est incompatible. Vérifiez sa version avant de continuer.", expected, received: object(data).contractVersion ?? null });
+    return data;
+}
+/** Provider envelopes/MIME and context snapshots are not evidence needed by the caller. */
+export function projectOutreachMessage(data) {
+    const m = object(data);
+    const result = pick(m, ["id", "organizationId", "programId", "decisionId", "senderId", "conversationId", "channel", "action", "recipient", "subject", "body", "expectedInboundId", "providerThreadId", "accountKey", "technicalParts", "state", "revision", "reasonCode", "expiresAt", "notBefore", "sentAt", "providerMessageId", "createdAt", "updatedAt"]);
+    if (m.decision)
+        result.decision = pick(m.decision, ["id", "personId", "leadId", "requestKey", "purpose", "reason", "sources", "contextVersion", "authorizationRevision", "contextReadAt", "receipt", "createdAt"]);
+    if (Array.isArray(m.attempts))
+        result.attempts = m.attempts.map(a => {
+            const attempt = pick(a, ["id", "ordinal", "startedAt", "providerBarrierAt", "finishedAt", "outcome", "providerMessageId", "errorCode", "lastReconciledAt", "reconciliationResult"]);
+            const receipt = object(object(object(a).providerRequest).receipt);
+            const safeReceipt = Object.fromEntries([["providerMessageId", receipt.id], ["providerThreadId", receipt.threadId]].filter(([, value]) => typeof value === "string"));
+            if (Object.keys(safeReceipt).length)
+                attempt.providerReceipt = safeReceipt;
+            return attempt;
+        });
+    return result;
+}
+export function registerAgentOutreachTools(server, client = getClient()) {
+    function register(name, description, schema, action, write = false) {
+        server.registerTool(name, { description: description + readNotice, inputSchema: schema,
+            annotations: { readOnlyHint: !write && name !== "query_outreach_prospects", destructiveHint: false, idempotentHint: name !== "query_outreach_prospects", openWorldHint: true } }, (async (input) => { try {
+            return toolResult(await action(schema.parse(input)));
+        }
+        catch (e) {
+            return outreachError(e);
+        } }));
+    }
+    register("list_outreach_programs", "List compact accessible autonomous outreach programs and the server contract version. Pagination: pass nextCursor unchanged as after_id.", z.object({ organization_id: identifier, after_id: identifier.optional(), limit: z.number().int().min(1).max(50).default(25) }).strict(), async (v) => requireOutreachVersion(await client.get("/api/agent-outreach/programs", params(v.organization_id, { afterId: v.after_id, limit: v.limit })), "1.0.0"));
+    register("get_outreach_program_context", "Read one program's rules, authorization revision and permitted sender identities. Cannot authorize, resume, raise caps, grant rights or change senders.", z.object(scope).strict(), async (v) => requireOutreachVersion(await client.get(programPath(v.program_id), params(v.organization_id)), "1.0.0"));
+    register("query_outreach_prospects", "Select canonical people server-side before pagination. Recipes: followup_due = seven days without pending/unknown/reply; channel_gap = LinkedIn messages >=2 and Gmail=0; replies_to_handle. For 72 hours set filters.last_confirmed_outbound_before.before to an explicit ISO timestamp. Signal filters support detection dates, levels and person/company scope. Keep cursor, filters and limit identical on continuation; selections expire after ten minutes. An incomplete history never proves no previous contact.", querySchema, async (v) => requireOutreachVersion(await client.post(postPath(`${programPath(v.program_id)}/prospects/query`, v.organization_id), queryBody(v)), "1.0.0"));
+    const personSchema = z.object({ ...scope, lead_id: identifier }).strict();
+    register("get_outreach_prospect_summary", "Read a selected person's compact identity, contact counts and selection reasons. This is NOT the writing context: use get_outreach_prospect_context before drafting.", personSchema, v => client.get(`${programPath(v.program_id)}/prospects/${encoded(v.lead_id)}`, params(v.organization_id)));
+    register("get_outreach_contact_history", "Read confirmed contact evidence for one person across accessible accounts, including pending, unknown and manual activity. Coverage limits remain explicit.", personSchema, v => client.get(`${programPath(v.program_id)}/contacts/${encoded(v.lead_id)}`, params(v.organization_id)));
+    register("get_outreach_prospect_context", "Read fresh writing context, full-thread readiness, identity, qualification, signals, exclusion, authorizations and Context Workspace. Draft only when readiness.ready=true; WAIT requires resolving the stated reasons. Copy all versions, factsVersion, contextVersion and readAt into the current decision. Never starts qualification. A human takeover can only be resumed by a human in Leadify.", personSchema, async (v) => requireOutreachVersion(await client.get(`${programPath(v.program_id, true)}/people/${encoded(v.lead_id)}/context`, params(v.organization_id)), "agent-writing-context.v1"));
+    register("get_outreach_thread", "Read one exact person's account/thread with complete bodies or explicit unavailable coverage. Pass nextCursor unchanged as cursor. An excerpt is not a complete conversation.", z.object({ ...scope, lead_id: identifier, account_key: z.string().min(1).max(1000), thread_id: identifier, cursor: z.string().min(1).max(8000).optional(), limit: z.number().int().min(1).max(100).default(50) }).strict(), v => client.get(`${programPath(v.program_id, true)}/people/${encoded(v.lead_id)}/thread`, params(v.organization_id, { accountKey: v.account_key, threadId: v.thread_id, cursor: v.cursor, limit: v.limit })));
+    register("submit_outreach_messages", "Deposit 1–20 fresh decisions to Leadify for now, at most one message per channel per person/decision, never a sequence or scheduled steps. Preserve authored text exactly. A reply requires thread_id and expected_inbound_id. Use the SAME request_key and identical payload after interruption; a changed payload needs a new decision after rereading context. Inspect EVERY receipt: a successful call may contain ACCEPTED, WAIT and REFUSED decisions." + receiptNotice, submitSchema, async (v) => requireOutreachVersion(await client.post(postPath(`${programPath(v.program_id)}/messages/batch`, v.organization_id), { decisions: v.decisions.map(decisionBody) }), "agent-message-receipt.v1"), true);
+    register("list_outreach_messages", "List this key's deposited messages and decision receipts, including after sender grant revocation. Pagination uses nextCursor as after_id." + receiptNotice, z.object({ ...scope, after_id: identifier.optional(), limit: z.number().int().min(1).max(50).default(25) }).strict(), async (v) => {
+        const data = object(await client.get(`${programPath(v.program_id)}/messages`, params(v.organization_id, { afterId: v.after_id, limit: v.limit })));
+        return { ...data, messages: Array.isArray(data.messages) ? data.messages.map(projectOutreachMessage) : data.messages };
+    });
+    register("get_outreach_message", "Read one deposited message, its decision receipt and safe provider attempt evidence. Raw provider envelopes and context snapshots are omitted." + receiptNotice, z.object({ ...scope, message_id: identifier }).strict(), async (v) => projectOutreachMessage(await client.get(`${programPath(v.program_id)}/messages/${encoded(v.message_id)}`, params(v.organization_id))));
+    register("cancel_outreach_message", "Cancel this key's message only before dispatch starts, with expected_revision from its latest read. SENDING, UNKNOWN and SENT return TOO_LATE; never treat that as cancellation.", z.object({ ...scope, message_id: identifier, expected_revision: z.number().int().nonnegative() }).strict(), async (v) => {
+        const data = object(await client.post(postPath(`${programPath(v.program_id)}/messages/${encoded(v.message_id)}/cancel`, v.organization_id), { expectedRevision: v.expected_revision }));
+        return { ...data, ...(data.message ? { message: projectOutreachMessage(data.message) } : {}) };
+    }, true);
+    register("list_outreach_events", "Read the durable consumer change journal, not the administrative audit log. Reading never advances processedCursor. Keep cursor/nextCursor unchanged; acknowledge every visible change through the chosen cursor only after handling it. Omit cursor to resume from this key's acknowledged position.", z.object({ ...scope, cursor: z.string().min(1).max(2000).optional(), limit: z.number().int().min(1).max(100).default(50) }).strict(), async (v) => requireOutreachVersion(await client.get(`${programPath(v.program_id, true)}/changes`, params(v.organization_id, { cursor: v.cursor, limit: v.limit })), "1.0.0"));
+    register("acknowledge_outreach_events", "Record PROCESSED or DISMISSED with a reason for every event in the complete visible prefix through cursor. This advances only this key's checkpoint. Retry the identical cursor and receipts after interruption; changed outcomes conflict. Never acknowledge an unhandled event.", acknowledgeSchema, async (v) => requireOutreachVersion(await client.post(postPath(`${programPath(v.program_id, true)}/changes/acknowledge`, v.organization_id), { cursor: v.cursor, receipts: v.receipts.map(r => ({ changeId: r.change_id, status: r.status, reason: r.reason })) }), "1.0.0"), true);
+    register("get_outreach_reception_health", "Read reception coverage and freshness for granted senders even while dispatch is off. READY covers only since program registration, not the whole historical mailbox.", z.object(scope).strict(), v => client.get(`${programPath(v.program_id)}/reception-health`, params(v.organization_id)));
+    register("list_outreach_conversations", "List received conversations for granted senders, optionally one person_id. Pagination uses nextCursor as after_id. This does not mark replies as handled.", z.object({ ...scope, after_id: identifier.optional(), person_id: identifier.optional(), limit: z.number().int().min(1).max(100).default(50) }).strict(), v => client.get(`${programPath(v.program_id)}/conversations`, params(v.organization_id, { afterId: v.after_id, personId: v.person_id, limit: v.limit })));
+    register("get_outreach_conversation", "Read persisted reception messages and human takeover state. Pass decimal nextCursor unchanged as after_id. This tool cannot take over or resume automation; human control belongs to Leadify.", z.object({ ...scope, conversation_id: identifier, after_id: z.string().regex(/^[0-9]{1,18}$/).optional(), limit: z.number().int().min(1).max(100).default(50) }).strict(), v => client.get(`${programPath(v.program_id)}/conversations/${encoded(v.conversation_id)}`, params(v.organization_id, { afterId: v.after_id, limit: v.limit })));
+}