@agifyai/leadify-mcp 8.5.4 → 8.6.1

package/dist/tools/personas.js

@@ -63,6 +63,17 @@ export const CRM_SCHEMA_PACKS = [
     "recruitment_hr",
     "community_creator",
 ];
+const optimisticPersonaMutationShape = {
+    organization_id: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Required organization ID; no tenant is inferred."),
+    expected_updated_at: z
+        .string()
+        .datetime({ offset: true })
+        .describe("Exact Persona updatedAt returned by the read that this edit is based on. A stale value is rejected with 409."),
+};
 const SECTOR_BASE_COMPATIBILITY = {
     healthcare: ["base_person", "base_company"],
     medtech: ["base_person", "base_company"],
@@ -174,10 +185,10 @@ class PersonaPatchError extends Error {
  * Strategy: fast-path the direct GET; on 404, fall back to the permissive
  * list endpoint and find by id. Other errors propagate immediately.
  */
-async function fetchPersona(id, client = getClient()) {
+async function fetchPersona(id, organizationId, client = getClient()) {
     const directPath = `/api/persona/${encodeURIComponent(id)}`;
     try {
-        const data = await client.get(directPath);
+        const data = await client.get(directPath, new URLSearchParams({ organizationId }));
         if (!data || typeof data !== "object") {
             throw new PersonaPatchError("read", directPath, null, data, "Unexpected response shape (expected an object).");
         }
@@ -192,12 +203,11 @@ async function fetchPersona(id, client = getClient()) {
         }
         // 404 on direct GET — fall through to list-based lookup.
     }
-    // Permissive fallback: list returns everything the API key can see
-    // (own org + globals for regular users; cross-org for super admins).
+    // Tenant-scoped fallback keeps the same explicit organization boundary.
     const listPath = "/api/persona";
     let listed;
     try {
-        listed = await client.get(listPath);
+        listed = await client.get(listPath, new URLSearchParams({ organizationId }));
     }
     catch (err) {
         if (err instanceof LeadifyApiError) {
@@ -218,12 +228,26 @@ async function fetchPersona(id, client = getClient()) {
     }
     return found;
 }
-async function postPersonaUpdate(id, name, fieldsToWrite, client = getClient()) {
+async function postPersonaUpdate(persona, fieldsToWrite, organizationId, expectedUpdatedAt, client = getClient()) {
     const path = "/api/persona";
+    if (typeof persona.verticalId !== "string" || persona.verticalId.length === 0) {
+        throw new PersonaPatchError("write", path, 409, { error: "PERSONA_VERTICAL_REQUIRED" }, "Historical global/orphaned Personas cannot be edited.");
+    }
+    if (typeof persona.updatedAt !== "string" ||
+        new Date(persona.updatedAt).toISOString() !== new Date(expectedUpdatedAt).toISOString()) {
+        throw new PersonaPatchError("write", path, 409, {
+            error: "CONTEXT_ENTITY_UPDATE_CONFLICT",
+            expectedUpdatedAt,
+            actualUpdatedAt: persona.updatedAt,
+        }, "Re-read the Persona and reapply the intended patch.");
+    }
     try {
         return await client.post(path, {
-            id,
-            name,
+            id: persona.id,
+            name: persona.name,
+            organizationId,
+            verticalId: persona.verticalId,
+            expectedUpdatedAt,
             ...fieldsToWrite,
         });
     }
@@ -271,18 +295,29 @@ export function registerPersonaTools(server, client) {
         "rewrite a persona. For partial edits, ALWAYS prefer the granular " +
         "update_persona_* tools — they do safe read-modify-write merges and avoid " +
         "wiping JSON columns you didn't intend to touch (each JSON column passed in " +
-        "this tool is replaced wholesale, so omitted sub-keys are LOST).", {
+        "this tool is replaced wholesale, so omitted sub-keys are LOST). PRD-1415 requires " +
+        "one explicit organization and one explicit Vertical; global/orphaned Personas are rejected.", {
         // core
         id: z
             .string()
             .optional()
             .describe("Persona ID to update an existing persona. Omit to create a new one."),
+        expected_updated_at: z
+            .string()
+            .datetime({ offset: true })
+            .optional()
+            .describe("Required on update: exact updatedAt from the Persona read this rewrite is based on. Omit on create."),
         name: z.string().describe("Persona name (required)."),
         organization_id: z
             .string()
-            .nullable()
-            .optional()
-            .describe("Target organization ID (Clerk org ID). Absent = caller's org. Pass null to make the persona global (admin only)."),
+            .trim()
+            .min(1)
+            .describe("Required target organization ID. There is no implicit tenant and no global Persona."),
+        vertical_id: z
+            .string()
+            .trim()
+            .min(1)
+            .describe("Required Vertical ID in the same organization."),
         description: z.string().optional().describe("Detailed persona description."),
         // targeting
         target_profile: z
@@ -386,6 +421,15 @@ export function registerPersonaTools(server, client) {
             .describe("Snippets inserted at named points. scope: 'qualify' | 'outreach'; insertion_point: 'prefix' | 'phase_1_5' | 'phase_2_extra' | 'suffix'."),
     }, async (params) => {
         try {
+            if (!params.organization_id) {
+                throw new Error("organization_id is required; no implicit tenant or global Persona is allowed.");
+            }
+            if (!params.vertical_id) {
+                throw new Error("vertical_id is required; an orphan Persona cannot be created or updated.");
+            }
+            if (params.id !== undefined && params.expected_updated_at === undefined) {
+                throw new Error("expected_updated_at is required when updating a Persona. Re-read it first; stale writes are rejected with 409.");
+            }
             if (params.id === undefined && params.schema_packs === undefined) {
                 throw new Error("schema_packs is required when creating a Persona. Call list_crm_schema_packs, then select exactly one base pack and at most one compatible sector pack.");
             }
@@ -394,11 +438,15 @@ export function registerPersonaTools(server, client) {
                 if (selectionError)
                     throw new Error(selectionError);
             }
-            const body = { name: params.name };
+            const body = {
+                name: params.name,
+                organizationId: params.organization_id,
+                verticalId: params.vertical_id,
+            };
             if (params.id !== undefined)
                 body.id = params.id;
-            if (params.organization_id !== undefined)
-                body.organizationId = params.organization_id;
+            if (params.expected_updated_at !== undefined)
+                body.expectedUpdatedAt = params.expected_updated_at;
             if (params.description !== undefined)
                 body.description = params.description;
             if (params.target_profile !== undefined)
@@ -467,20 +515,21 @@ export function registerPersonaTools(server, client) {
         "Reads the current Persona, validates exactly one workflow-compatible base and at most one " +
         "compatible sector pack, then writes schemaPacks through the canonical Persona endpoint. " +
         "The response includes the persisted Persona and readiness proofs for every linked group.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID to update."),
         schema_packs: z
             .array(z.enum(CRM_SCHEMA_PACKS))
             .min(1)
             .describe("Complete replacement selection. Call list_crm_schema_packs first."),
-    }, async ({ id, schema_packs }) => {
+    }, async ({ organization_id, expected_updated_at, id, schema_packs }) => {
         try {
             const api = client ?? getClient();
-            const persona = await fetchPersona(id, api);
+            const persona = await fetchPersona(id, organization_id, api);
             const workflowMode = persona.workflowMode === "company_first" ? "company_first" : "person_first";
             const selectionError = crmSchemaPackSelectionError(schema_packs, workflowMode);
             if (selectionError)
                 throw new Error(selectionError);
-            const data = await postPersonaUpdate(id, persona.name, { schemaPacks: schema_packs }, api);
+            const data = await postPersonaUpdate(persona, { schemaPacks: schema_packs }, organization_id, expected_updated_at, api);
             return toolResult(data);
         }
         catch (error) {
@@ -494,6 +543,11 @@ export function registerPersonaTools(server, client) {
         "qualification concerns (~37k chars instead of ~63k). Pass include_outreach=true to " +
         "get the full payload — but for outreach-only reads prefer get_outreach_templates " +
         "(a much smaller, dedicated read).", {
+        organization_id: z
+            .string()
+            .trim()
+            .min(1)
+            .describe("Required organization ID; no tenant is inferred."),
         id: z.string().describe("Persona ID."),
         include_outreach: z
             .boolean()
@@ -502,9 +556,9 @@ export function registerPersonaTools(server, client) {
             .describe("If true, keep the outreach trio in the response (outreachTemplates, " +
             "outreachSignalRouting, outreachFields). Default false (SILO: outreach lives " +
             "in its own tool)."),
-    }, async ({ id, include_outreach }) => {
+    }, async ({ organization_id, id, include_outreach }) => {
         try {
-            const data = await (client ?? getClient()).get(`/api/persona/${encodeURIComponent(id)}`);
+            const data = await (client ?? getClient()).get(`/api/persona/${encodeURIComponent(id)}`, new URLSearchParams({ organizationId: organization_id }));
             // SILO defense in depth: strip the outreach trio locally unless the
             // caller explicitly opted in. Outreach data belongs to the dedicated
             // outreach tools — never mix it with the persona read by default.
@@ -548,12 +602,13 @@ export function registerPersonaTools(server, client) {
             // persona below to grab the outreach trio.
             const groupPersona = (await (client ?? getClient()).get(`/api/lead-group/${encodeURIComponent(lead_group_id)}/persona`));
             const personaId = groupPersona?.persona?.id;
-            if (!personaId) {
-                return toolError(`No persona is assigned to lead group "${lead_group_id}". ` +
-                    `Assign one via update_lead_group({ persona_id }) before reading outreach templates.`);
+            const organizationId = groupPersona?.organizationId;
+            if (!personaId || !organizationId) {
+                return toolError(`No usable tenant-scoped Persona is assigned to lead group "${lead_group_id}". ` +
+                    `Assign one ACTIVE Persona linked to a Vertical before reading outreach templates.`);
             }
             // Step 2: fetch the full persona so we can project the trio.
-            const full = (await (client ?? getClient()).get(`/api/persona/${encodeURIComponent(personaId)}`));
+            const full = (await (client ?? getClient()).get(`/api/persona/${encodeURIComponent(personaId)}`, new URLSearchParams({ organizationId })));
             // The API may return either a bare persona or {persona: {...}}.
             const persona = full.persona ?? full;
             const trio = {
@@ -573,32 +628,42 @@ export function registerPersonaTools(server, client) {
             return handlePersonaToolError(error);
         }
     });
+    // ── change_persona_status ─────────────────────────────────────────────
+    server.tool("change_persona_status", "Change one tenant-scoped Persona between DRAFT, ACTIVE, and ARCHIVED. " +
+        "The exact expected_updated_at from the caller's read is mandatory. Activation requires an ACTIVE Vertical " +
+        "plus qualification-ready content; archive is blocked while durable references remain; ARCHIVED can only return to DRAFT.", {
+        ...optimisticPersonaMutationShape,
+        id: z.string().min(1).describe("Persona ID."),
+        status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]),
+    }, async ({ organization_id, expected_updated_at, id, status }) => {
+        try {
+            const query = new URLSearchParams({ organizationId: organization_id });
+            const data = await (client ?? getClient()).post(`/api/persona/${encodeURIComponent(id)}/status?${query.toString()}`, { expectedUpdatedAt: expected_updated_at, status });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handlePersonaToolError(error);
+        }
+    });
     // ── list_personas ──────────────────────────────────────────────────────
-    server.tool("list_personas", "List all personas accessible to the caller, optionally scoped to a specific organization " +
-        "and/or including global personas. Use this to discover persona IDs before calling " +
+    server.tool("list_personas", "List all usable Persona records in one explicit organization. Historical global/orphaned " +
+        "Personas are excluded and available only through the reviewed migration inventory. Use this to discover persona IDs before calling " +
         "get_persona, upsert_persona (for updates), or assigning a persona to a lead group. " +
         "Returns a COMPACT view by default (id, name, organizationId, truncated description) " +
         "to avoid blowing up context — full persona objects can be heavy (~10k chars each). " +
         "Pass verbose=true to get the full objects, or call get_persona(id) for a single full persona.", {
         organization_id: z
             .string()
-            .optional()
-            .describe("Filter by organization ID. Pass the literal string 'null' to list only global personas."),
-        include_globals: z
-            .boolean()
-            .optional()
-            .describe("If true (default), include global personas (organizationId === null) alongside org-scoped ones."),
+            .trim()
+            .min(1)
+            .describe("Required organization ID. The literal string 'null' and implicit tenant selection are forbidden."),
         verbose: z
             .boolean()
             .optional()
             .describe("If true, return full persona objects with every field. Defaults to false (compact view: id, name, organizationId, short description)."),
-    }, async ({ organization_id, include_globals, verbose }) => {
+    }, async ({ organization_id, verbose }) => {
         try {
-            const params = new URLSearchParams();
-            if (organization_id !== undefined)
-                params.set("organizationId", organization_id);
-            if (include_globals !== undefined)
-                params.set("includeGlobals", String(include_globals));
+            const params = new URLSearchParams({ organizationId: organization_id });
             const data = await (client ?? getClient()).get("/api/persona", params);
             if (verbose)
                 return toolResult(data);
@@ -615,7 +680,9 @@ export function registerPersonaTools(server, client) {
                 return {
                     id: obj.id,
                     name: obj.name,
-                    organizationId: obj.organizationId ?? null,
+                    organizationId: obj.organizationId,
+                    verticalId: obj.verticalId,
+                    status: obj.status,
                     ...(desc !== undefined && {
                         description: desc.length > DESC_MAX ? `${desc.slice(0, DESC_MAX)}…` : desc,
                     }),
@@ -631,38 +698,6 @@ export function registerPersonaTools(server, client) {
             return handlePersonaToolError(error);
         }
     });
-    // ── delete_persona ─────────────────────────────────────────────────────
-    server.tool("delete_persona", "Permanently delete a persona by ID. Irreversible. Fails if the persona is still assigned " +
-        "to any lead group or referenced by an active campaign. Always confirm with the user " +
-        "before calling this tool.", {
-        id: z.string().describe("Persona ID to delete."),
-    }, async ({ id }) => {
-        try {
-            const data = await (client ?? getClient()).delete(`/api/persona/${encodeURIComponent(id)}`);
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── move_persona ───────────────────────────────────────────────────────
-    server.tool("move_persona", "Move a persona to a different organization (or make it global by passing null). " +
-        "Admin permission required. Useful when promoting an org-scoped persona to a shared " +
-        "global template, or reassigning between orgs.", {
-        id: z.string().describe("Persona ID to move."),
-        organization_id: z
-            .string()
-            .nullable()
-            .describe("Target organization ID (Clerk org ID). Pass null to make the persona global."),
-    }, async ({ id, organization_id }) => {
-        try {
-            const data = await (client ?? getClient()).post(`/api/persona/${encodeURIComponent(id)}/move`, { organizationId: organization_id });
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
     // ════════════════════════════════════════════════════════════════════════
     // GRANULAR PATCH TOOLS — read-modify-write, scoped to one section each
     // ════════════════════════════════════════════════════════════════════════
@@ -670,6 +705,7 @@ export function registerPersonaTools(server, client) {
     server.tool("update_persona_identity", "Patch top-level scalar fields of a persona (name, description, " +
         "output_language, workflow_mode, strict_match, enable_signals). " +
         "Pass only the fields you want to change. Other persona sections are untouched.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         name: z.string().min(1).optional().describe("New persona name."),
         description: z.string().nullable().optional().describe("Detailed description."),
@@ -691,7 +727,7 @@ export function registerPersonaTools(server, client) {
             .boolean()
             .optional()
             .describe("Enable business signal detection for this persona."),
-    }, async ({ id, name, description, output_language, workflow_mode, strict_match, enable_signals, }) => {
+    }, async ({ organization_id, expected_updated_at, id, name, description, output_language, workflow_mode, strict_match, enable_signals, }) => {
         try {
             if (name === undefined &&
                 description === undefined &&
@@ -701,7 +737,7 @@ export function registerPersonaTools(server, client) {
                 enable_signals === undefined) {
                 return toolError("Provide at least one field to update.");
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const body = {};
             if (description !== undefined)
                 body.description = description;
@@ -713,7 +749,7 @@ export function registerPersonaTools(server, client) {
                 body.strictMatch = strict_match;
             if (enable_signals !== undefined)
                 body.enableSignals = enable_signals;
-            const data = await postPersonaUpdate(id, name ?? current.name, body, client ?? getClient());
+            const data = await postPersonaUpdate({ ...current, name: name ?? current.name }, body, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -726,6 +762,7 @@ export function registerPersonaTools(server, client) {
         "keys: job_titles, specialties, seniority_min, decision_maker, buying_power, " +
         "target_company_types, min_company_size, interest_topics. Other targetProfile " +
         "keys remain intact.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         patch: z
             .record(z.unknown())
@@ -735,17 +772,17 @@ export function registerPersonaTools(server, client) {
             .array(z.string())
             .optional()
             .describe("Keys to delete from targetProfile."),
-    }, async ({ id, patch, remove_keys }) => {
+    }, async ({ organization_id, expected_updated_at, id, patch, remove_keys }) => {
         try {
             if ((patch === undefined || Object.keys(patch).length === 0) &&
                 (remove_keys === undefined || remove_keys.length === 0)) {
                 return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const next = { ...asObject(current.targetProfile), ...(patch ?? {}) };
             for (const k of remove_keys ?? [])
                 delete next[k];
-            const data = await postPersonaUpdate(id, current.name, { targetProfile: next }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { targetProfile: next }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -755,6 +792,7 @@ export function registerPersonaTools(server, client) {
     // ── update_persona_disqualification ────────────────────────────────────
     server.tool("update_persona_disqualification", "Patch the disqualificationCriteria JSON column (shallow merge). Common key: " +
         "reasons (array of strings). Other keys remain intact.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         patch: z
             .record(z.unknown())
@@ -764,17 +802,17 @@ export function registerPersonaTools(server, client) {
             .array(z.string())
             .optional()
             .describe("Keys to delete from disqualificationCriteria."),
-    }, async ({ id, patch, remove_keys }) => {
+    }, async ({ organization_id, expected_updated_at, id, patch, remove_keys }) => {
         try {
             if ((patch === undefined || Object.keys(patch).length === 0) &&
                 (remove_keys === undefined || remove_keys.length === 0)) {
                 return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const next = { ...asObject(current.disqualificationCriteria), ...(patch ?? {}) };
             for (const k of remove_keys ?? [])
                 delete next[k];
-            const data = await postPersonaUpdate(id, current.name, { disqualificationCriteria: next }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { disqualificationCriteria: next }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -785,6 +823,7 @@ export function registerPersonaTools(server, client) {
     server.tool("update_persona_active_tools", "Replace the activeTools list wholesale, OR add/remove specific entries while " +
         "preserving the rest. Use 'tools' to fully replace; use 'add' / 'remove' for " +
         "incremental edits (deduped).", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         tools: z
             .array(z.string())
@@ -798,7 +837,7 @@ export function registerPersonaTools(server, client) {
             .array(z.string())
             .optional()
             .describe("Tools to remove (no-op if absent)."),
-    }, async ({ id, tools, add, remove }) => {
+    }, async ({ organization_id, expected_updated_at, id, tools, add, remove }) => {
         try {
             if (tools === undefined && add === undefined && remove === undefined) {
                 return toolError("Provide one of: tools, add, remove.");
@@ -806,7 +845,7 @@ export function registerPersonaTools(server, client) {
             if (tools !== undefined && (add !== undefined || remove !== undefined)) {
                 return toolError("'tools' is mutually exclusive with 'add' / 'remove'.");
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             let next;
             if (tools !== undefined) {
                 next = tools;
@@ -819,7 +858,7 @@ export function registerPersonaTools(server, client) {
                     set.delete(t);
                 next = Array.from(set);
             }
-            const data = await postPersonaUpdate(id, current.name, { activeTools: next }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { activeTools: next }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -832,6 +871,7 @@ export function registerPersonaTools(server, client) {
         "{criteria, examples, weight}. When passing a structured patch, sub-fields are " +
         "merged into the existing structured tier (if any) — pass only what you want " +
         "to change. Passing a string REPLACES the tier entirely.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         tier: z
             .enum(["hot", "warm", "cold", "disqualified"])
@@ -848,7 +888,7 @@ export function registerPersonaTools(server, client) {
                 .passthrough(),
         ])
             .describe("New tier value. String replaces wholesale; object is merged."),
-    }, async ({ id, tier, criteria }) => {
+    }, async ({ organization_id, expected_updated_at, id, tier, criteria }) => {
         try {
             const fieldMap = {
                 hot: "hotCriteria",
@@ -857,7 +897,7 @@ export function registerPersonaTools(server, client) {
                 disqualified: "disqualifiedCriteria",
             };
             const field = fieldMap[tier];
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             let nextValue;
             if (typeof criteria === "string") {
                 nextValue = criteria;
@@ -869,7 +909,7 @@ export function registerPersonaTools(server, client) {
                     : {};
                 nextValue = { ...base, ...criteria };
             }
-            const data = await postPersonaUpdate(id, current.name, { [field]: nextValue }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { [field]: nextValue }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -881,6 +921,7 @@ export function registerPersonaTools(server, client) {
         "list. Lookups are by client `name` (case-sensitive exact match). Reads the " +
         "current lookalikeClients array, mutates the matched entry, writes the full " +
         "list back. Use this instead of upsert_persona to avoid wiping the others.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         action: z
             .enum(["add", "replace", "remove"])
@@ -892,7 +933,7 @@ export function registerPersonaTools(server, client) {
         client: lookalikeClient
             .optional()
             .describe("Client payload. Required for 'add' and 'replace'. Schema: {name, sector?, size?, segment?, comparison_criteria?}."),
-    }, async ({ id, action, name, client: lookalikeClientInput }) => {
+    }, async ({ organization_id, expected_updated_at, id, action, name, client: lookalikeClientInput }) => {
         try {
             if ((action === "add" || action === "replace") && !lookalikeClientInput) {
                 return toolError(`client is required for action '${action}'.`);
@@ -900,7 +941,7 @@ export function registerPersonaTools(server, client) {
             if ((action === "replace" || action === "remove") && !name) {
                 return toolError(`name is required for action '${action}'.`);
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const list = asArray(current.lookalikeClients).map((c) => ({ ...c }));
             if (action === "add") {
                 const newName = lookalikeClientInput.name;
@@ -925,9 +966,7 @@ export function registerPersonaTools(server, client) {
                 list.length = 0;
                 list.push(...filtered);
             }
-            const data = await postPersonaUpdate(id, current.name, {
-                lookalikeClients: list,
-            }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { lookalikeClients: list }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -938,6 +977,7 @@ export function registerPersonaTools(server, client) {
     server.tool("update_persona_pain_point", "Add, replace, or remove a single pain point without re-sending the whole list. " +
         "Pain points have no stable id — entries are addressed by zero-based index. " +
         "Beware: indices shift after a remove, so re-fetch before chaining edits.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         action: z
             .enum(["add", "replace", "remove"])
@@ -951,7 +991,7 @@ export function registerPersonaTools(server, client) {
         pain: painPoint
             .optional()
             .describe("Pain payload {title?, description?}. Required for 'add' and 'replace'."),
-    }, async ({ id, action, index, pain }) => {
+    }, async ({ organization_id, expected_updated_at, id, action, index, pain }) => {
         try {
             if ((action === "add" || action === "replace") && !pain) {
                 return toolError(`pain is required for action '${action}'.`);
@@ -959,7 +999,7 @@ export function registerPersonaTools(server, client) {
             if ((action === "replace" || action === "remove") && index === undefined) {
                 return toolError(`index is required for action '${action}'.`);
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const list = asArray(current.painPoints).map((p) => ({ ...p }));
             if (action === "add") {
                 list.push(pain);
@@ -976,7 +1016,7 @@ export function registerPersonaTools(server, client) {
                 }
                 list.splice(index, 1);
             }
-            const data = await postPersonaUpdate(id, current.name, { painPoints: list }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { painPoints: list }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -988,6 +1028,7 @@ export function registerPersonaTools(server, client) {
         "tone_instructions, context). Each is a separate scalar JSON column — passing " +
         "one replaces it (pass null to clear). Other prompt fields and persona sections " +
         "remain intact.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         normalization_rules: z
             .string()
@@ -1009,7 +1050,7 @@ export function registerPersonaTools(server, client) {
             .nullable()
             .optional()
             .describe("Markdown appended to the ICP prompt. Null clears it."),
-    }, async ({ id, normalization_rules, signal_guidance, tone_instructions, context, }) => {
+    }, async ({ organization_id, expected_updated_at, id, normalization_rules, signal_guidance, tone_instructions, context, }) => {
         try {
             if (normalization_rules === undefined &&
                 signal_guidance === undefined &&
@@ -1017,7 +1058,7 @@ export function registerPersonaTools(server, client) {
                 context === undefined) {
                 return toolError("Provide at least one field to update.");
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const body = {};
             if (normalization_rules !== undefined)
                 body.normalizationRules = normalization_rules;
@@ -1027,7 +1068,7 @@ export function registerPersonaTools(server, client) {
                 body.toneInstructions = tone_instructions;
             if (context !== undefined)
                 body.context = context;
-            const data = await postPersonaUpdate(id, current.name, body, client ?? getClient());
+            const data = await postPersonaUpdate(current, body, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {
@@ -1040,6 +1081,7 @@ export function registerPersonaTools(server, client) {
         "decisionDrivers[]}. Reads current icpStrategy, shallow-merges the keys you " +
         "pass, optionally removes specified keys. Arrays (mainPains, keyObjections, " +
         "decisionDrivers) are REPLACED wholesale when passed.", {
+        ...optimisticPersonaMutationShape,
         id: z.string().describe("Persona ID."),
         dealType: z
             .string()
@@ -1069,7 +1111,7 @@ export function registerPersonaTools(server, client) {
             .array(z.string())
             .optional()
             .describe("Keys to delete from icpStrategy."),
-    }, async ({ id, dealType, dreamOutcome, mainPains, keyObjections, decisionDrivers, patch, remove_keys, }) => {
+    }, async ({ organization_id, expected_updated_at, id, dealType, dreamOutcome, mainPains, keyObjections, decisionDrivers, patch, remove_keys, }) => {
         try {
             if (dealType === undefined &&
                 dreamOutcome === undefined &&
@@ -1080,7 +1122,7 @@ export function registerPersonaTools(server, client) {
                 (remove_keys === undefined || remove_keys.length === 0)) {
                 return toolError("Provide at least one field to update.");
             }
-            const current = await fetchPersona(id, client ?? getClient());
+            const current = await fetchPersona(id, organization_id, client ?? getClient());
             const next = { ...asObject(current.icpStrategy) };
             if (dealType !== undefined)
                 next.dealType = dealType;
@@ -1096,7 +1138,7 @@ export function registerPersonaTools(server, client) {
                 Object.assign(next, patch);
             for (const k of remove_keys ?? [])
                 delete next[k];
-            const data = await postPersonaUpdate(id, current.name, { icpStrategy: next }, client ?? getClient());
+            const data = await postPersonaUpdate(current, { icpStrategy: next }, organization_id, expected_updated_at, client ?? getClient());
             return toolResult(data);
         }
         catch (error) {

package/dist/tools/pipeline.d.ts

@@ -1,2 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerPipelineTools(server: McpServer): void;
+import { type LeadifyClient } from "../client.js";
+type PipelineClient = Pick<LeadifyClient, "get" | "post">;
+export declare function registerPipelineTools(server: McpServer, client?: PipelineClient): void;
+export {};