@leadbay/mcp 0.33.0 → 0.33.2

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog — @leadbay/mcp
 
+## 0.33.2 — 2026-09-02
+
+Editing one field on a contact erased the others (product#4046).
+
+Reproduced on production while verifying leadbay/mcp#194: sending a contact's
+own current `first_name` + `last_name` + `job_title`, changing nothing, deleted
+that contact's email. The contact moved from `contacts.reachable` to
+`contacts.candidates` and `_meta.has_reachable_contact` flipped to false, so the
+lead stopped being contactable. Restored with a second call.
+
+This became reachable only the day before: until #194 the tool returned 404 on
+100% of calls, so it destroyed nothing. A tool that always failed now succeeded
+and deleted data.
+
+**The backend already had the safe behaviour and we were choosing the other
+one.** Both routes take the same payload
+(`OrgContactRoutes.kt:110,152` → `OrgContactsDaoImpl.kt:265-272`):
+
+| Route | `forceUpdateIfNullOrEmpty` | A field absent from the body |
+|---|---|---|
+| `/contacts/{id}/update` | `true` | written as null — **erased** |
+| `/contacts/{id}/merge` | `false` | skipped — **kept** |
+
+So the fix needs no read-modify-write, no extra round-trip and no race window.
+`leadbay_update_contact` now routes by intent:
+
+- **Nothing being erased → `/merge`.** Every field the caller omitted survives.
+- **Any field passed as `null` → `/update`**, which rewrites the record — so
+  that call must carry all four optional fields. If it does not, the tool
+  refuses with `CONTACT_CLEAR_NEEDS_FULL_RECORD` rather than deleting what was
+  not mentioned. The destructive path costs more effort than the safe one,
+  which is the intended asymmetry.
+- The result carries `mode` (`merge` / `replace`), `preserved` and `cleared`, so
+  a wrong edit is visible rather than silent.
+
+Verified live on staging, same body to each route:
+
+```
+POST /contacts/{id}/merge   {first_name, last_name, job_title:"CEO"}
+  → job_title CEO,  email merge.probe@example.test,  phone +15550001111   (kept)
+POST /contacts/{id}/update  {first_name, last_name, job_title:"CTO"}
+  → job_title CTO,  email absent,  phone absent                           (erased)
+```
+
+Two existing test files were changed rather than added, because both asserted
+the contract this fixes: `update-contact.test.ts`'s happy path now expects
+`/merge`, and `update-contact-null-clear.test.ts`'s clear case now supplies the
+whole record. The second had encoded the data loss as correct — it asserted that
+unmentioned fields are not sent, while posting to the route that deletes them.
+
+## 0.33.1 — 2026-09-02
+
+Follow-up to 0.32.0 (product#4007). A review finding landed after the merge.
+
+- **Only a REFUSAL counts as a commit failure.** The detached finisher's catch
+  recorded ANY rejection from the `pollPreprocess` → `commitMappings` chain as a
+  permanent commit failure — including the `ImportPhaseTimeout` raised when
+  preprocess still hasn't finished after the finisher's own 10-minute window.
+  That is not a backend refusal; the import is merely slow and may yet finish.
+  The registry has no expiry, so `leadbay_import_status` would have answered
+  `failed` for ever on a healthy import — worse than the forever-polling 0.32.0
+  set out to remove. A budget timeout now leaves the status at `committing`,
+  which is the honest reading; only an error from `commitMappings` itself is
+  recorded.
+- The finisher's window is deliberately not caller-controllable — a caller
+  shrinking it is the bug that budget exists to prevent — so the test reaches it
+  through a named module seam beside the existing `clearCommitFailures`, rather
+  than a parameter that would leak into the tool's public schema.
+
 ## 0.33.0 — 2026-09-01
 
 Agent memory is removed (product#3996). The three `leadbay_agent_memory_*`

package/dist/bin.js

@@ -5692,7 +5692,7 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass its \`contact_id\`, first_name, last_name and only the fields being changed
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -5725,11 +5725,30 @@ Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
 
 A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
-**\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
+## Omitting a field keeps it. Erasing one takes an explicit \`null\`.
 
-Backend: \`POST /contacts/{contact_id}/update\` (snake_case body) \u2192 200 with the updated contact. Edits in place (same id). Camel-case bodies are rejected.
+Send only what you are changing. Any field you leave out keeps its current value \u2014 you do NOT need to read the contact first and echo everything back.
 
-Returns \`{ updated: true, contact_id, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
+\`\`\`
+{ contact_id, first_name, last_name, job_title: "CEO" }
+\u2192 title becomes CEO. email, phone and LinkedIn are untouched.
+\`\`\`
+
+**To erase a field, pass it as \`null\`.** Because erasing rewrites the whole record, that call must carry ALL of \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\` \u2014 current value for the ones to keep, \`null\` for the ones to erase. If any are missing the call is refused with \`CONTACT_CLEAR_NEEDS_FULL_RECORD\` rather than deleting them; read the contact with \`leadbay_research_lead_by_id\` and re-call.
+
+\`\`\`
+{ contact_id, first_name, last_name, email: null,
+  job_title: "CEO", phone_number: "+33\u2026", linkedin_page: "https://\u2026" }
+\u2192 email erased, everything else as given.
+\`\`\`
+
+\`first_name\` + \`last_name\` are required on every call. The backend validates the contact's identity and rejects a body without them (\`invalid contact\`), so pass the current values when you are not changing the name.
+
+The result tells you which happened: \`mode\` is \`merge\` or \`replace\`, \`preserved\` lists the fields left untouched, \`cleared\` lists the fields erased. **Check \`cleared\` is what you intended.**
+
+Backend: \`POST /contacts/{contact_id}/merge\` when nothing is being erased, \`POST /contacts/{contact_id}/update\` when something is. Snake_case body; camel-case is rejected. Edits in place (same id).
+
+Returns \`{ updated: true, contact_id, mode, preserved, cleared, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -9389,7 +9408,15 @@ function resumeParkedUpload(client, upload, mappings, ctx) {
   const { importId } = upload;
   setTimeout(() => {
     void (async () => {
-      await pollPreprocess(client, importId, RESUME_COMMIT_BUDGET_MS, bgCtx, void 0);
+      try {
+        await pollPreprocess(client, importId, resumeCommitBudgetMs, bgCtx, void 0);
+      } catch (err) {
+        if (err instanceof ImportPhaseTimeout) {
+          bgCtx.logger?.warn?.(`import-leads: parked upload ${importId} still preprocessing after ${resumeCommitBudgetMs}ms; leaving it to the backend`);
+          return;
+        }
+        throw err;
+      }
       await commitMappings(client, importId, mappings, bgCtx);
     })().then(() => ctx?.logger?.info?.(`import-leads: parked upload ${importId} committed; backend is processing`), (err) => {
       recordCommitFailure(importId, err?.message ?? err?.code ?? "mapping commit failed");
@@ -9437,7 +9464,7 @@ async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, ha
     })();
   }, 0);
 }
-var CHUNK_SIZE, POLL_INTERVAL_MS2, DEFAULT_PER_PHASE_BUDGET_MS, DEFAULT_TOTAL_BUDGET_MS, STABILIZATION_POLLS, MAX_COLUMN_NAME_LEN, RESERVED_COLUMN_RE, CUSTOM_FIELD_RE, IMPORT_RESOLVER_FIELDS, ImportPhaseTimeout, LEAD_STATUSES, LEAD_STATUS_SET, importLeads, RESUME_COMMIT_BUDGET_MS;
+var CHUNK_SIZE, POLL_INTERVAL_MS2, DEFAULT_PER_PHASE_BUDGET_MS, DEFAULT_TOTAL_BUDGET_MS, STABILIZATION_POLLS, MAX_COLUMN_NAME_LEN, RESERVED_COLUMN_RE, CUSTOM_FIELD_RE, IMPORT_RESOLVER_FIELDS, ImportPhaseTimeout, LEAD_STATUSES, LEAD_STATUS_SET, importLeads, DEFAULT_RESUME_COMMIT_BUDGET_MS, resumeCommitBudgetMs;
 var init_import_leads = __esm({
   "../core/dist/composite/import-leads.js"() {
     "use strict";
@@ -9829,7 +9856,8 @@ var init_import_leads = __esm({
         return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds);
       }
     };
-    RESUME_COMMIT_BUDGET_MS = 10 * 6e4;
+    DEFAULT_RESUME_COMMIT_BUDGET_MS = 10 * 6e4;
+    resumeCommitBudgetMs = DEFAULT_RESUME_COMMIT_BUDGET_MS;
   }
 });
 
@@ -11864,39 +11892,59 @@ var init_update_contact = __esm({
           // new value. execute forwards null verbatim; the backend accepts it.
           job_title: {
             type: ["string", "null"],
-            description: "Contact job title. Pass null to clear it."
+            description: "Contact job title. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           },
           linkedin_page: {
             type: ["string", "null"],
-            description: "Contact LinkedIn URL. Pass null to clear it."
+            description: "Contact LinkedIn URL. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           },
           email: {
             type: ["string", "null"],
-            description: "Contact email. Pass null to clear it."
+            description: "Contact email. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           },
           phone_number: {
             type: ["string", "null"],
-            description: "Contact phone (free-form). Pass null to clear it."
+            description: "Contact phone (free-form). Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
           }
         },
         required: ["contact_id", "first_name", "last_name"],
         additionalProperties: false
       },
       execute: async (client, params, _ctx) => {
+        const OPTIONAL = ["job_title", "linkedin_page", "email", "phone_number"];
+        const asked = (f) => params[f] !== void 0;
+        const clearing = OPTIONAL.filter((f) => params[f] === null);
         const body = {
           first_name: params.first_name,
           last_name: params.last_name
         };
-        if (params.job_title !== void 0)
-          body.job_title = params.job_title;
-        if (params.linkedin_page !== void 0)
-          body.linkedin_page = params.linkedin_page;
-        if (params.email !== void 0)
-          body.email = params.email;
-        if (params.phone_number !== void 0)
-          body.phone_number = params.phone_number;
+        for (const f of OPTIONAL)
+          if (asked(f))
+            body[f] = params[f];
+        if (clearing.length === 0) {
+          const contact2 = await client.request("POST", `/contacts/${params.contact_id}/merge`, body);
+          return {
+            updated: true,
+            contact_id: params.contact_id,
+            contact: contact2,
+            mode: "merge",
+            preserved: OPTIONAL.filter((f) => !asked(f)),
+            cleared: []
+          };
+        }
+        const missing = OPTIONAL.filter((f) => !asked(f));
+        if (missing.length > 0) {
+          throw client.makeError("CONTACT_CLEAR_NEEDS_FULL_RECORD", `Clearing ${clearing.join(", ")} rewrites the whole contact, and ${missing.join(", ")} ${missing.length === 1 ? "was" : "were"} not supplied`, `Read the contact (leadbay_research_lead_by_id) and re-call with ALL of ${OPTIONAL.join(", ")} \u2014 current value to keep it, null to clear it. Omitting a field here would delete it.`, `POST /contacts/${params.contact_id}/update`);
+        }
         const contact = await client.request("POST", `/contacts/${params.contact_id}/update`, body);
-        return { updated: true, contact_id: params.contact_id, contact };
+        return {
+          updated: true,
+          contact_id: params.contact_id,
+          contact,
+          mode: "replace",
+          preserved: [],
+          cleared: clearing
+        };
       }
     };
   }
@@ -27853,7 +27901,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.33.0";
+var VERSION = "0.33.2";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -8283,7 +8283,7 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass its \`contact_id\`, first_name, last_name and only the fields being changed
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -8316,11 +8316,30 @@ Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
 
 A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
-**\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
+## Omitting a field keeps it. Erasing one takes an explicit \`null\`.
 
-Backend: \`POST /contacts/{contact_id}/update\` (snake_case body) \u2192 200 with the updated contact. Edits in place (same id). Camel-case bodies are rejected.
+Send only what you are changing. Any field you leave out keeps its current value \u2014 you do NOT need to read the contact first and echo everything back.
 
-Returns \`{ updated: true, contact_id, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
+\`\`\`
+{ contact_id, first_name, last_name, job_title: "CEO" }
+\u2192 title becomes CEO. email, phone and LinkedIn are untouched.
+\`\`\`
+
+**To erase a field, pass it as \`null\`.** Because erasing rewrites the whole record, that call must carry ALL of \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\` \u2014 current value for the ones to keep, \`null\` for the ones to erase. If any are missing the call is refused with \`CONTACT_CLEAR_NEEDS_FULL_RECORD\` rather than deleting them; read the contact with \`leadbay_research_lead_by_id\` and re-call.
+
+\`\`\`
+{ contact_id, first_name, last_name, email: null,
+  job_title: "CEO", phone_number: "+33\u2026", linkedin_page: "https://\u2026" }
+\u2192 email erased, everything else as given.
+\`\`\`
+
+\`first_name\` + \`last_name\` are required on every call. The backend validates the contact's identity and rejects a body without them (\`invalid contact\`), so pass the current values when you are not changing the name.
+
+The result tells you which happened: \`mode\` is \`merge\` or \`replace\`, \`preserved\` lists the fields left untouched, \`cleared\` lists the fields erased. **Check \`cleared\` is what you intended.**
+
+Backend: \`POST /contacts/{contact_id}/merge\` when nothing is being erased, \`POST /contacts/{contact_id}/update\` when something is. Snake_case body; camel-case is rejected. Edits in place (same id).
+
+Returns \`{ updated: true, contact_id, mode, preserved, cleared, contact: { id, first_name, last_name, job_title, linkedin_page, email, phone_number } }\`.
 
 Requires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw).
 `;
@@ -12159,13 +12178,22 @@ var importLeads = {
     return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds);
   }
 };
-var RESUME_COMMIT_BUDGET_MS = 10 * 6e4;
+var DEFAULT_RESUME_COMMIT_BUDGET_MS = 10 * 6e4;
+var resumeCommitBudgetMs = DEFAULT_RESUME_COMMIT_BUDGET_MS;
 function resumeParkedUpload(client, upload, mappings, ctx) {
   const bgCtx = { logger: ctx?.logger };
   const { importId } = upload;
   setTimeout(() => {
     void (async () => {
-      await pollPreprocess(client, importId, RESUME_COMMIT_BUDGET_MS, bgCtx, void 0);
+      try {
+        await pollPreprocess(client, importId, resumeCommitBudgetMs, bgCtx, void 0);
+      } catch (err) {
+        if (err instanceof ImportPhaseTimeout) {
+          bgCtx.logger?.warn?.(`import-leads: parked upload ${importId} still preprocessing after ${resumeCommitBudgetMs}ms; leaving it to the backend`);
+          return;
+        }
+        throw err;
+      }
       await commitMappings(client, importId, mappings, bgCtx);
     })().then(() => ctx?.logger?.info?.(`import-leads: parked upload ${importId} committed; backend is processing`), (err) => {
       recordCommitFailure(importId, err?.message ?? err?.code ?? "mapping commit failed");
@@ -13991,39 +14019,59 @@ var updateContact = {
       // new value. execute forwards null verbatim; the backend accepts it.
       job_title: {
         type: ["string", "null"],
-        description: "Contact job title. Pass null to clear it."
+        description: "Contact job title. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       },
       linkedin_page: {
         type: ["string", "null"],
-        description: "Contact LinkedIn URL. Pass null to clear it."
+        description: "Contact LinkedIn URL. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       },
       email: {
         type: ["string", "null"],
-        description: "Contact email. Pass null to clear it."
+        description: "Contact email. Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       },
       phone_number: {
         type: ["string", "null"],
-        description: "Contact phone (free-form). Pass null to clear it."
+        description: "Contact phone (free-form). Omit it to leave it unchanged. Pass null to ERASE it \u2014 an erase rewrites the whole contact, so that call must also carry every other optional field, or it is refused."
       }
     },
     required: ["contact_id", "first_name", "last_name"],
     additionalProperties: false
   },
   execute: async (client, params, _ctx) => {
+    const OPTIONAL = ["job_title", "linkedin_page", "email", "phone_number"];
+    const asked = (f) => params[f] !== void 0;
+    const clearing = OPTIONAL.filter((f) => params[f] === null);
     const body = {
       first_name: params.first_name,
       last_name: params.last_name
     };
-    if (params.job_title !== void 0)
-      body.job_title = params.job_title;
-    if (params.linkedin_page !== void 0)
-      body.linkedin_page = params.linkedin_page;
-    if (params.email !== void 0)
-      body.email = params.email;
-    if (params.phone_number !== void 0)
-      body.phone_number = params.phone_number;
+    for (const f of OPTIONAL)
+      if (asked(f))
+        body[f] = params[f];
+    if (clearing.length === 0) {
+      const contact2 = await client.request("POST", `/contacts/${params.contact_id}/merge`, body);
+      return {
+        updated: true,
+        contact_id: params.contact_id,
+        contact: contact2,
+        mode: "merge",
+        preserved: OPTIONAL.filter((f) => !asked(f)),
+        cleared: []
+      };
+    }
+    const missing = OPTIONAL.filter((f) => !asked(f));
+    if (missing.length > 0) {
+      throw client.makeError("CONTACT_CLEAR_NEEDS_FULL_RECORD", `Clearing ${clearing.join(", ")} rewrites the whole contact, and ${missing.join(", ")} ${missing.length === 1 ? "was" : "were"} not supplied`, `Read the contact (leadbay_research_lead_by_id) and re-call with ALL of ${OPTIONAL.join(", ")} \u2014 current value to keep it, null to clear it. Omitting a field here would delete it.`, `POST /contacts/${params.contact_id}/update`);
+    }
     const contact = await client.request("POST", `/contacts/${params.contact_id}/update`, body);
-    return { updated: true, contact_id: params.contact_id, contact };
+    return {
+      updated: true,
+      contact_id: params.contact_id,
+      contact,
+      mode: "replace",
+      preserved: [],
+      cleared: clearing
+    };
   }
 };
 
@@ -24620,7 +24668,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.33.0" : "0.0.0-dev";
+var VERSION = true ? "0.33.2" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var logger = {

package/dist/installer-electron.js

@@ -1804,7 +1804,7 @@ var init_installer_gui = __esm({
     init_install_dxt();
     init_install_shared();
     init_oauth();
-    VERSION = true ? "0.33.0" : "0.0.0-dev";
+    VERSION = true ? "0.33.2" : "0.0.0-dev";
     MESSAGES = {
       en: {
         installer: {

package/dist/installer-gui.js

@@ -1067,7 +1067,7 @@ async function oauthLogin(opts) {
 }
 
 // installer/installer-gui.ts
-var VERSION = true ? "0.33.0" : "0.0.0-dev";
+var VERSION = true ? "0.33.2" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",