@leadbay/mcp 0.30.0 → 0.31.0

package/dist/bin.js

@@ -8596,6 +8596,11 @@ WHEN NOT TO USE: when the user has named a specific lens \u2014 pass \`lensId\`
 
 The active lens can change between calls (5-min cache + backend \`last_requested_lens\`). If a multi-step workflow depends on staying on one lens, **capture \`response.lens.id\` from the first response and pass it as the \`lensId\` argument on every subsequent Leadbay call** \u2014 including re-pulls, bulk qualifies, and research. (Field-name caveat: response nests it as \`lens.id\`; the parameter is \`lensId\`.) Re-pulling without \`lensId\` after a long-running tool may silently switch to a different lens and discard prior work.
 
+**EMPTY BATCH \u2014 route on \`empty_reason\`, never loop.** When \`leads\` is empty the response carries \`empty_reason: {code, message, retryable, criteria?, narrow_locations?}\`. \`retryable\` is the only field that decides what you do next:
+
+- \`retryable: true\` (always \`code: "computing"\`) \u2014 the lens is still building. Say so, pull ONCE more in ~30s. Do not call it empty.
+- \`retryable: false\` \u2014 no amount of re-pulling, lens-switching or \`leadbay_extend_lens\` can produce leads on these criteria. **Stop calling tools.** Surface \`message\` to the user, name the criteria from \`criteria\` (and \`narrow_locations\` first when present \u2014 a city-scale geo scope is the usual culprit), and offer \`leadbay_adjust_audience\` to widen. A refill on a zero-candidate lens answers "queued", consumes no quota and delivers nothing, so retrying reads as progress while achieving none (product#3995).
+
 ---
 
 ## RENDERING \u2014 markdown table, three columns, score-bar driven
@@ -16481,6 +16486,107 @@ var init_prepare_outreach = __esm({
   }
 });
 
+// ../core/dist/composite/_empty-lens-reason.js
+function criteriaOf(filter) {
+  return filter?.lens_filter?.items?.flatMap((i) => i.criteria ?? []) ?? [];
+}
+function summariseCriteria(criteria) {
+  const out = {};
+  for (const c of criteria) {
+    if (c.type === "sector_ids") {
+      const key = c.is_excluded ? "excluded_sector_ids" : "sector_ids";
+      out[key] = [...out[key] ?? [], ...c.sectors ?? []];
+    } else if (c.type === "location_ids") {
+      const key = c.is_excluded ? "excluded_location_ids" : "location_ids";
+      out[key] = [...out[key] ?? [], ...c.locations ?? []];
+    } else if (c.type === "size" && !c.is_excluded) {
+      out.sizes = [...out.sizes ?? [], ...c.sizes ?? []];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function narrowLocationsOf(filter, criteria) {
+  const included = new Set(criteria.filter((c) => c.type === "location_ids" && !c.is_excluded).flatMap((c) => c.locations ?? []));
+  if (included.size === 0)
+    return [];
+  const results = filter?.locations?.results ?? [];
+  return results.filter((r) => typeof r.id === "string" && included.has(r.id) && typeof r.level === "number" && r.level >= CITY_LEVEL).map((r) => ({
+    id: r.id,
+    name: typeof r.name === "string" ? r.name : "",
+    level: r.level
+  }));
+}
+function narrowGeoSentence(narrow) {
+  const names = narrow.map((n) => n.name).filter(Boolean);
+  if (names.length === 0)
+    return "";
+  return ` Its geography is pinned to ${names.join(", ")} \u2014 a city-scale area or smaller, which on an empty lens is almost always the criterion to relax first.`;
+}
+async function diagnoseEmptyLens(client, lensId, computing) {
+  if (computing.wishlist || computing.scores) {
+    return {
+      code: "computing",
+      retryable: true,
+      message: "This lens is still computing its leads. Pull again in ~30s \u2014 do NOT report it as empty yet."
+    };
+  }
+  let row;
+  try {
+    const lenses = await client.request("GET", "/lenses");
+    row = lenses.find((l) => String(l.id) === String(lensId));
+  } catch {
+  }
+  let filter = null;
+  try {
+    filter = await client.request("GET", `/lenses/${lensId}/filter`);
+  } catch {
+  }
+  const criteria = criteriaOf(filter);
+  const summary = summariseCriteria(criteria);
+  const narrow = narrowLocationsOf(filter, criteria);
+  const geo = narrowGeoSentence(narrow);
+  const extras = {
+    ...summary ? { criteria: summary } : {},
+    ...narrow.length > 0 ? { narrow_locations: narrow } : {}
+  };
+  if (row?.not_enough_lead_candidates) {
+    return {
+      code: "no_candidates",
+      retryable: false,
+      message: "This lens's criteria match no companies in the database, so it cannot fill." + geo + " Tell the user and offer to widen the audience (leadbay_adjust_audience) \u2014 extending or re-pulling will not help.",
+      ...extras
+    };
+  }
+  if (row?.not_enough_new_leads) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: "Every company matching this lens has already been delivered \u2014 there are no NEW leads left on these criteria. Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the existing leads via leadbay_pull_followups.",
+      ...extras
+    };
+  }
+  if (summary) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens is finished computing and holds zero leads: its criteria intersect to nothing." + geo + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience). Do NOT call leadbay_extend_lens \u2014 a refill on a zero-candidate lens reports queued, consumes no quota, and delivers nothing.",
+      ...extras
+    };
+  }
+  return {
+    code: "unknown",
+    retryable: false,
+    message: "This lens is finished computing and holds zero leads, and carries no audience criteria that would explain it. Report this to the user rather than retrying; leadbay_report_friction is the way to flag it to the Leadbay team."
+  };
+}
+var CITY_LEVEL;
+var init_empty_lens_reason = __esm({
+  "../core/dist/composite/_empty-lens-reason.js"() {
+    "use strict";
+    CITY_LEVEL = 7;
+  }
+});
+
 // ../core/dist/composite/pull-leads.js
 function normalizeLinkedinPage3(v) {
   if (v == null)
@@ -16561,6 +16667,7 @@ var init_pull_leads = __esm({
   "../core/dist/composite/pull-leads.js"() {
     "use strict";
     init_agent_memory();
+    init_empty_lens_reason();
     init_tool_descriptions_generated();
     pullLeads = {
       name: "leadbay_pull_leads",
@@ -16626,6 +16733,34 @@ var init_pull_leads = __esm({
             type: "boolean",
             description: "True if scoring is still running."
           },
+          empty_reason: {
+            type: ["object", "null"],
+            description: "Why this LENS holds zero leads. null whenever leads were returned, and null when this page is empty only because it is past the end of a non-empty lens. `retryable` is the field to route on: true ONLY on code=computing (pull again in ~30s). On every other code re-pulling and leadbay_extend_lens are both futile \u2014 a refill on a zero-candidate lens answers 'queued', consumes no quota and delivers nothing \u2014 so surface `message` to the user and offer leadbay_adjust_audience instead of retrying.",
+            properties: {
+              code: {
+                type: "string",
+                description: "computing | no_candidates | no_new_leads | audience_too_narrow | unknown"
+              },
+              message: {
+                type: "string",
+                description: "The line to surface to the user."
+              },
+              retryable: {
+                type: "boolean",
+                description: "True only while the lens is still computing. False means no amount of re-pulling or extending can produce leads."
+              },
+              criteria: {
+                type: "object",
+                description: "The lens criteria in play \u2014 what the user would have to relax. Present when the lens carries any."
+              },
+              narrow_locations: {
+                type: "array",
+                description: "Include-locations that resolved to a city-scale area or smaller ({id, name, level}). On an empty lens, name these first: this is the fingerprint of a whole-country location that fell through to a same-named village (product#3951).",
+                items: { type: "object" }
+              }
+            },
+            required: ["code", "message", "retryable"]
+          },
           next_steps: {
             type: ["object", "null"],
             description: "Ready-made NEXT STEPS for the host's choice widget. Each option has a SHORT `label` (\u22645 words, fits AskUserQuestion's label cap on Claude cowork/Claude Code) and a full `description`. For AskUserQuestion (cowork/Claude Code) pass each option as {label, description}. For ask_user_input_v0 (Claude chat/ChatGPT, string-only options) use the `description` as the option string. Use these VERBATIM, in order \u2014 do NOT re-derive, reword, or render as prose when a widget tool exists. options[0] is the artifact offer (build the lead triage board) whenever the batch is non-empty; options[1] is the enrich offer (kind:enrich_top_leads \u2014 route it to leadbay_enrich_titles scoped to the leadIds JUST shown (pass leads[].id + the pinned lens.id) with NO titles, so it runs the no-spend discovery preview; quota is only spent after the user picks titles + confirms channels on a follow-up call). When the batch is empty but the lens is still computing (computing_wishlist/computing_scores true), this carries a 'Re-pull in ~30s' option (kind:repull_computing) plus 'Refine audience' \u2014 render the widget so the user waits rather than seeing 'no leads.' null only when the batch is empty AND nothing is computing (a genuinely empty / over-narrow lens).",
@@ -16726,6 +16861,11 @@ var init_pull_leads = __esm({
           computingWishlist: res.computing_wishlist,
           computingScores: res.computing_scores
         });
+        const lensIsEmpty = leadCount === 0 && (res.pagination?.total ?? 0) === 0;
+        const emptyReason = lensIsEmpty ? await diagnoseEmptyLens(client, lensId, {
+          wishlist: res.computing_wishlist,
+          scores: res.computing_scores
+        }) : null;
         return withAgentMemoryMeta(client, {
           lens: { id: lensId },
           leads: res.items.map((lead) => ({
@@ -16737,6 +16877,7 @@ var init_pull_leads = __esm({
           next_page: nextPage,
           computing_wishlist: res.computing_wishlist,
           computing_scores: res.computing_scores,
+          empty_reason: emptyReason,
           next_steps: nextSteps,
           _meta: {
             region: client.region,
@@ -31730,7 +31871,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.30.0";
+var VERSION = "0.31.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -10924,6 +10924,11 @@ WHEN NOT TO USE: when the user has named a specific lens \u2014 pass \`lensId\`
 
 The active lens can change between calls (5-min cache + backend \`last_requested_lens\`). If a multi-step workflow depends on staying on one lens, **capture \`response.lens.id\` from the first response and pass it as the \`lensId\` argument on every subsequent Leadbay call** \u2014 including re-pulls, bulk qualifies, and research. (Field-name caveat: response nests it as \`lens.id\`; the parameter is \`lensId\`.) Re-pulling without \`lensId\` after a long-running tool may silently switch to a different lens and discard prior work.
 
+**EMPTY BATCH \u2014 route on \`empty_reason\`, never loop.** When \`leads\` is empty the response carries \`empty_reason: {code, message, retryable, criteria?, narrow_locations?}\`. \`retryable\` is the only field that decides what you do next:
+
+- \`retryable: true\` (always \`code: "computing"\`) \u2014 the lens is still building. Say so, pull ONCE more in ~30s. Do not call it empty.
+- \`retryable: false\` \u2014 no amount of re-pulling, lens-switching or \`leadbay_extend_lens\` can produce leads on these criteria. **Stop calling tools.** Surface \`message\` to the user, name the criteria from \`criteria\` (and \`narrow_locations\` first when present \u2014 a city-scale geo scope is the usual culprit), and offer \`leadbay_adjust_audience\` to widen. A refill on a zero-candidate lens answers "queued", consumes no quota and delivers nothing, so retrying reads as progress while achieving none (product#3995).
+
 ---
 
 ## RENDERING \u2014 markdown table, three columns, score-bar driven
@@ -18328,6 +18333,101 @@ var prepareOutreach = {
   }
 };
 
+// ../core/dist/composite/_empty-lens-reason.js
+var CITY_LEVEL = 7;
+function criteriaOf(filter) {
+  return filter?.lens_filter?.items?.flatMap((i) => i.criteria ?? []) ?? [];
+}
+function summariseCriteria(criteria) {
+  const out = {};
+  for (const c of criteria) {
+    if (c.type === "sector_ids") {
+      const key = c.is_excluded ? "excluded_sector_ids" : "sector_ids";
+      out[key] = [...out[key] ?? [], ...c.sectors ?? []];
+    } else if (c.type === "location_ids") {
+      const key = c.is_excluded ? "excluded_location_ids" : "location_ids";
+      out[key] = [...out[key] ?? [], ...c.locations ?? []];
+    } else if (c.type === "size" && !c.is_excluded) {
+      out.sizes = [...out.sizes ?? [], ...c.sizes ?? []];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function narrowLocationsOf(filter, criteria) {
+  const included = new Set(criteria.filter((c) => c.type === "location_ids" && !c.is_excluded).flatMap((c) => c.locations ?? []));
+  if (included.size === 0)
+    return [];
+  const results = filter?.locations?.results ?? [];
+  return results.filter((r) => typeof r.id === "string" && included.has(r.id) && typeof r.level === "number" && r.level >= CITY_LEVEL).map((r) => ({
+    id: r.id,
+    name: typeof r.name === "string" ? r.name : "",
+    level: r.level
+  }));
+}
+function narrowGeoSentence(narrow) {
+  const names = narrow.map((n) => n.name).filter(Boolean);
+  if (names.length === 0)
+    return "";
+  return ` Its geography is pinned to ${names.join(", ")} \u2014 a city-scale area or smaller, which on an empty lens is almost always the criterion to relax first.`;
+}
+async function diagnoseEmptyLens(client, lensId, computing) {
+  if (computing.wishlist || computing.scores) {
+    return {
+      code: "computing",
+      retryable: true,
+      message: "This lens is still computing its leads. Pull again in ~30s \u2014 do NOT report it as empty yet."
+    };
+  }
+  let row;
+  try {
+    const lenses = await client.request("GET", "/lenses");
+    row = lenses.find((l) => String(l.id) === String(lensId));
+  } catch {
+  }
+  let filter = null;
+  try {
+    filter = await client.request("GET", `/lenses/${lensId}/filter`);
+  } catch {
+  }
+  const criteria = criteriaOf(filter);
+  const summary = summariseCriteria(criteria);
+  const narrow = narrowLocationsOf(filter, criteria);
+  const geo = narrowGeoSentence(narrow);
+  const extras = {
+    ...summary ? { criteria: summary } : {},
+    ...narrow.length > 0 ? { narrow_locations: narrow } : {}
+  };
+  if (row?.not_enough_lead_candidates) {
+    return {
+      code: "no_candidates",
+      retryable: false,
+      message: "This lens's criteria match no companies in the database, so it cannot fill." + geo + " Tell the user and offer to widen the audience (leadbay_adjust_audience) \u2014 extending or re-pulling will not help.",
+      ...extras
+    };
+  }
+  if (row?.not_enough_new_leads) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: "Every company matching this lens has already been delivered \u2014 there are no NEW leads left on these criteria. Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the existing leads via leadbay_pull_followups.",
+      ...extras
+    };
+  }
+  if (summary) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens is finished computing and holds zero leads: its criteria intersect to nothing." + geo + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience). Do NOT call leadbay_extend_lens \u2014 a refill on a zero-candidate lens reports queued, consumes no quota, and delivers nothing.",
+      ...extras
+    };
+  }
+  return {
+    code: "unknown",
+    retryable: false,
+    message: "This lens is finished computing and holds zero leads, and carries no audience criteria that would explain it. Report this to the user rather than retrying; leadbay_report_friction is the way to flag it to the Leadbay team."
+  };
+}
+
 // ../core/dist/composite/pull-leads.js
 function normalizeLinkedinPage3(v) {
   if (v == null)
@@ -18467,6 +18567,34 @@ var pullLeads = {
         type: "boolean",
         description: "True if scoring is still running."
       },
+      empty_reason: {
+        type: ["object", "null"],
+        description: "Why this LENS holds zero leads. null whenever leads were returned, and null when this page is empty only because it is past the end of a non-empty lens. `retryable` is the field to route on: true ONLY on code=computing (pull again in ~30s). On every other code re-pulling and leadbay_extend_lens are both futile \u2014 a refill on a zero-candidate lens answers 'queued', consumes no quota and delivers nothing \u2014 so surface `message` to the user and offer leadbay_adjust_audience instead of retrying.",
+        properties: {
+          code: {
+            type: "string",
+            description: "computing | no_candidates | no_new_leads | audience_too_narrow | unknown"
+          },
+          message: {
+            type: "string",
+            description: "The line to surface to the user."
+          },
+          retryable: {
+            type: "boolean",
+            description: "True only while the lens is still computing. False means no amount of re-pulling or extending can produce leads."
+          },
+          criteria: {
+            type: "object",
+            description: "The lens criteria in play \u2014 what the user would have to relax. Present when the lens carries any."
+          },
+          narrow_locations: {
+            type: "array",
+            description: "Include-locations that resolved to a city-scale area or smaller ({id, name, level}). On an empty lens, name these first: this is the fingerprint of a whole-country location that fell through to a same-named village (product#3951).",
+            items: { type: "object" }
+          }
+        },
+        required: ["code", "message", "retryable"]
+      },
       next_steps: {
         type: ["object", "null"],
         description: "Ready-made NEXT STEPS for the host's choice widget. Each option has a SHORT `label` (\u22645 words, fits AskUserQuestion's label cap on Claude cowork/Claude Code) and a full `description`. For AskUserQuestion (cowork/Claude Code) pass each option as {label, description}. For ask_user_input_v0 (Claude chat/ChatGPT, string-only options) use the `description` as the option string. Use these VERBATIM, in order \u2014 do NOT re-derive, reword, or render as prose when a widget tool exists. options[0] is the artifact offer (build the lead triage board) whenever the batch is non-empty; options[1] is the enrich offer (kind:enrich_top_leads \u2014 route it to leadbay_enrich_titles scoped to the leadIds JUST shown (pass leads[].id + the pinned lens.id) with NO titles, so it runs the no-spend discovery preview; quota is only spent after the user picks titles + confirms channels on a follow-up call). When the batch is empty but the lens is still computing (computing_wishlist/computing_scores true), this carries a 'Re-pull in ~30s' option (kind:repull_computing) plus 'Refine audience' \u2014 render the widget so the user waits rather than seeing 'no leads.' null only when the batch is empty AND nothing is computing (a genuinely empty / over-narrow lens).",
@@ -18567,6 +18695,11 @@ var pullLeads = {
       computingWishlist: res.computing_wishlist,
       computingScores: res.computing_scores
     });
+    const lensIsEmpty = leadCount === 0 && (res.pagination?.total ?? 0) === 0;
+    const emptyReason = lensIsEmpty ? await diagnoseEmptyLens(client, lensId, {
+      wishlist: res.computing_wishlist,
+      scores: res.computing_scores
+    }) : null;
     return withAgentMemoryMeta(client, {
       lens: { id: lensId },
       leads: res.items.map((lead) => ({
@@ -18578,6 +18711,7 @@ var pullLeads = {
       next_page: nextPage,
       computing_wishlist: res.computing_wishlist,
       computing_scores: res.computing_scores,
+      empty_reason: emptyReason,
       next_steps: nextSteps,
       _meta: {
         region: client.region,
@@ -28307,7 +28441,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.30.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.0" : "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.30.0" : "0.0.0-dev";
+    VERSION = true ? "0.31.0" : "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.30.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.0" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "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",