@leadbay/mcp 0.31.0 → 0.31.1

package/dist/bin.js

@@ -6832,8 +6832,10 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 \`queued\` \u2192 \u2705 "Queued <N> extra leads on lens <id>. Pull in ~30s." Do NOT
 list \`accepted_seeds\`; they're internal.
-\`quota_exceeded\` \u2192 render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`) (smaller
-count / wait until reset / upgrade).
+\`no_candidates\` \u2192 \u26D4 surface \`reason.message\`, name the criteria, offer
+\`leadbay_adjust_audience\`. Never re-call this tool on that lens.
+\`quota_exceeded\` \u2192 three options via the host's choice widget
+(smaller count / wait for reset / upgrade).
 \`refresh_in_progress\` \u2192 "lens is filling, retry in a minute".
 \`no_valid_seeds\` \u2192 silently re-call \`leadbay_seed_candidates\`, retry once.
 
@@ -6853,6 +6855,9 @@ Queue an additive extra-refill on a lens \u2014 more leads on the same criteria,
 - \`status: "quota_exceeded"\` \u2014 daily LENS_EXTRA_REFILL hit. Response carries \`quota: {used_today, resets_at}\` + a \`message\` to surface. **Render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`)**: (1) smaller \`extra_count\`, (2) wait until \`resets_at\`, (3) upgrade plan (TIER1=150, TIER2=1000). Do NOT silently retry.
 - \`status: "refresh_in_progress"\` \u2014 a refresh or extra-refill is already running. Tell the user to wait and call \`leadbay_pull_leads\` in ~30s.
 - \`status: "no_valid_seeds"\` \u2014 seeds went stale. Silently re-call \`leadbay_seed_candidates\` and retry once; only surface to the user if the second attempt also fails.
+- \`status: "no_candidates"\` \u2014 **the refill was NOT queued.** The lens's candidate pool is empty, so a refill would report success, consume no quota and deliver nothing. \`reason\` carries the same \`{code, message, retryable, criteria?, narrow_locations?}\` shape \`leadbay_pull_leads\` returns in \`empty_reason\`, with \`retryable: false\`. **Stop. Do not re-call this tool on this lens** \u2014 the outcome cannot change until the audience changes. Surface \`reason.message\`, name the criteria in play, and offer \`leadbay_adjust_audience\` (or \`leadbay_pull_followups\` when \`reason.code\` is \`no_new_leads\` and the lens already holds leads).
+
+**Extendability is checked before the write.** Every response carries \`available_count\` \u2014 how many leads a refill could still draw, read from the lens's own pool. \`0\` means the call was refused (\`no_candidates\`); \`null\` means the pool could not be read and the refill was queued anyway. An empty lens is NOT evidence of a broken refill: it is usually a lens that never had candidates. Reach for \`leadbay_adjust_audience\`, not another \`leadbay_extend_lens\`.
 
 WHEN TO USE: when the user has a bigger appetite than the daily lens fill delivers \u2014 they want MORE of the same kind of leads, on demand. Canonical phrasings: "I want more leads on this lens", "extend the lens", "give me a bigger batch today". The \`leadbay_extend_my_lens\` prompt is the user-facing entry point that orchestrates the whole flow.
 
@@ -6893,6 +6898,8 @@ Pick the row matching the response \`status\`. Seed-picking is internal; do NOT
 | \`quota_exceeded\`        | "Upgrade plan for a higher daily limit"                       | (no call \u2014 direct user to contact account manager / sales) |
 | \`refresh_in_progress\`   | "Lens is already filling \u2014 pull leads in a minute"            | \`leadbay_pull_leads()\` (after a short wait)            |
 | \`no_valid_seeds\`        | (silent retry \u2014 re-call \`leadbay_seed_candidates\` then \`leadbay_extend_lens\`) | internal \u2014 only surface if the second attempt also fails |
+| \`no_candidates\`         | "Widen the audience \u2014 this lens has nothing left to add"       | \`leadbay_adjust_audience()\` \u2014 never \`leadbay_extend_lens\` again |
+| \`no_candidates\` (\`reason.code: no_new_leads\`) | "Work the leads already in the lens"        | \`leadbay_pull_followups()\`                             |
 
 If nothing matches cleanly, default to "pull leads now to see what's queued" \u2014 never invent a tool that doesn't exist.
 `;
@@ -16522,6 +16529,21 @@ function narrowGeoSentence(narrow) {
     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 readAudienceShape(client, lensId) {
+  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);
+  return {
+    ...summary ? { criteria: summary } : {},
+    ...narrow.length > 0 ? { narrow_locations: narrow } : {},
+    geoSentence: narrowGeoSentence(narrow)
+  };
+}
 async function diagnoseEmptyLens(client, lensId, computing) {
   if (computing.wishlist || computing.scores) {
     return {
@@ -16536,19 +16558,8 @@ async function diagnoseEmptyLens(client, lensId, computing) {
     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 } : {}
-  };
+  const { geoSentence: geo, ...extras } = await readAudienceShape(client, lensId);
+  const summary = extras.criteria;
   if (row?.not_enough_lead_candidates) {
     return {
       code: "no_candidates",
@@ -24177,11 +24188,54 @@ async function readExtraRefillQuota(client) {
     return { count: null, resets_at: null };
   }
 }
+async function readAvailablePool(client, lensId) {
+  try {
+    const preview = await client.request("GET", `/lenses/${lensId}/extra_refill_preview`);
+    return typeof preview?.available_count === "number" ? preview.available_count : null;
+  } catch {
+    return null;
+  }
+}
+async function readLensLeadTotal(client, lensId) {
+  try {
+    const page = await client.request("GET", `/lenses/${lensId}/leads/wishlist?count=1&page=0`);
+    return typeof page?.pagination?.total === "number" ? page.pagination.total : null;
+  } catch {
+    return null;
+  }
+}
+function noCandidatesReason(held, shape) {
+  const { geoSentence, ...extras } = shape;
+  const futile = " Extending again is futile \u2014 a refill on a lens with an empty candidate pool reports queued, consumes no quota and delivers nothing.";
+  if (held === 0) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens holds no leads and has none left to add: its criteria intersect to nothing." + geoSentence + futile + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience).",
+      ...extras
+    };
+  }
+  if (held !== null) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: `Every company matching this lens has already been delivered \u2014 all ${held} of them \u2014 so there is nothing left to add.` + futile + " Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the leads already in the lens (leadbay_pull_followups).",
+      ...extras
+    };
+  }
+  return {
+    code: "no_candidates",
+    retryable: false,
+    message: "This lens has no candidates left to add." + geoSentence + futile + " Tell the user and offer to widen the audience (leadbay_adjust_audience).",
+    ...extras
+  };
+}
 var extendLens;
 var init_extend_lens = __esm({
   "../core/dist/composite/extend-lens.js"() {
     "use strict";
     init_tool_descriptions_generated();
+    init_empty_lens_reason();
     extendLens = {
       name: "leadbay_extend_lens",
       annotations: {
@@ -24218,7 +24272,7 @@ var init_extend_lens = __esm({
         properties: {
           status: {
             type: "string",
-            description: "queued | quota_exceeded | refresh_in_progress | no_valid_seeds"
+            description: "queued | no_candidates | quota_exceeded | refresh_in_progress | no_valid_seeds"
           },
           lens: {
             type: "object",
@@ -24233,6 +24287,35 @@ var init_extend_lens = __esm({
             type: "string",
             description: "Human-readable summary. On error statuses, this is the line to surface to the user."
           },
+          available_count: {
+            type: ["number", "null"],
+            description: "How many leads a refill on this lens could still draw, read from /extra_refill_preview before queueing. 0 means the refill was NOT queued (status=no_candidates). null means the pool could not be read and the refill was queued anyway."
+          },
+          reason: {
+            type: "object",
+            description: "Only present on status=no_candidates. Same shape and `code` vocabulary as leadbay_pull_leads' empty_reason, so one routing rule covers both tools.",
+            properties: {
+              code: {
+                type: "string",
+                description: "audience_too_narrow (lens holds nothing and its criteria intersect to nothing) | no_new_leads (everything matching has already been delivered) | no_candidates (pool is empty; which of the two could not be determined)"
+              },
+              message: { type: "string" },
+              retryable: {
+                type: "boolean",
+                description: "Always false here. Re-calling leadbay_extend_lens cannot change the outcome \u2014 widen the audience instead."
+              },
+              criteria: {
+                type: "object",
+                description: "The criteria in play, so the agent can name them."
+              },
+              narrow_locations: {
+                type: "array",
+                description: "Include-locations that resolved to city-scale or smaller \u2014 the usual thing to relax first.",
+                items: { type: "object" }
+              }
+            },
+            required: ["code", "message", "retryable"]
+          },
           quota: {
             type: "object",
             description: "Only present on status=quota_exceeded. Shows the org's daily LENS_EXTRA_REFILL state.",
@@ -24246,6 +24329,21 @@ var init_extend_lens = __esm({
       },
       execute: async (client, params) => {
         const lensId = params.lensId ?? await client.resolveDefaultLens();
+        const availableCount = await readAvailablePool(client, lensId);
+        if (availableCount === 0) {
+          const [shape, held] = await Promise.all([
+            readAudienceShape(client, lensId),
+            readLensLeadTotal(client, lensId)
+          ]);
+          const reason = noCandidatesReason(held, shape);
+          return {
+            status: "no_candidates",
+            lens: { id: lensId },
+            available_count: 0,
+            reason,
+            message: reason.message
+          };
+        }
         const body = {
           seed_lead_ids: params.seed_lead_ids ?? []
         };
@@ -24257,6 +24355,7 @@ var init_extend_lens = __esm({
           return {
             status: "queued",
             lens: { id: lensId },
+            available_count: availableCount,
             accepted_seeds: res.accepted_seeds,
             message: "Extra refill queued. Leads stream in asynchronously \u2014 call leadbay_pull_leads in ~30s to see them."
           };
@@ -31871,7 +31970,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.31.0";
+var VERSION = "0.31.1";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -9160,8 +9160,10 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 \`queued\` \u2192 \u2705 "Queued <N> extra leads on lens <id>. Pull in ~30s." Do NOT
 list \`accepted_seeds\`; they're internal.
-\`quota_exceeded\` \u2192 render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`) (smaller
-count / wait until reset / upgrade).
+\`no_candidates\` \u2192 \u26D4 surface \`reason.message\`, name the criteria, offer
+\`leadbay_adjust_audience\`. Never re-call this tool on that lens.
+\`quota_exceeded\` \u2192 three options via the host's choice widget
+(smaller count / wait for reset / upgrade).
 \`refresh_in_progress\` \u2192 "lens is filling, retry in a minute".
 \`no_valid_seeds\` \u2192 silently re-call \`leadbay_seed_candidates\`, retry once.
 
@@ -9181,6 +9183,9 @@ Queue an additive extra-refill on a lens \u2014 more leads on the same criteria,
 - \`status: "quota_exceeded"\` \u2014 daily LENS_EXTRA_REFILL hit. Response carries \`quota: {used_today, resets_at}\` + a \`message\` to surface. **Render three options via your host's choice widget (\`ask_user_input_v0\` or \`AskUserQuestion\`)**: (1) smaller \`extra_count\`, (2) wait until \`resets_at\`, (3) upgrade plan (TIER1=150, TIER2=1000). Do NOT silently retry.
 - \`status: "refresh_in_progress"\` \u2014 a refresh or extra-refill is already running. Tell the user to wait and call \`leadbay_pull_leads\` in ~30s.
 - \`status: "no_valid_seeds"\` \u2014 seeds went stale. Silently re-call \`leadbay_seed_candidates\` and retry once; only surface to the user if the second attempt also fails.
+- \`status: "no_candidates"\` \u2014 **the refill was NOT queued.** The lens's candidate pool is empty, so a refill would report success, consume no quota and deliver nothing. \`reason\` carries the same \`{code, message, retryable, criteria?, narrow_locations?}\` shape \`leadbay_pull_leads\` returns in \`empty_reason\`, with \`retryable: false\`. **Stop. Do not re-call this tool on this lens** \u2014 the outcome cannot change until the audience changes. Surface \`reason.message\`, name the criteria in play, and offer \`leadbay_adjust_audience\` (or \`leadbay_pull_followups\` when \`reason.code\` is \`no_new_leads\` and the lens already holds leads).
+
+**Extendability is checked before the write.** Every response carries \`available_count\` \u2014 how many leads a refill could still draw, read from the lens's own pool. \`0\` means the call was refused (\`no_candidates\`); \`null\` means the pool could not be read and the refill was queued anyway. An empty lens is NOT evidence of a broken refill: it is usually a lens that never had candidates. Reach for \`leadbay_adjust_audience\`, not another \`leadbay_extend_lens\`.
 
 WHEN TO USE: when the user has a bigger appetite than the daily lens fill delivers \u2014 they want MORE of the same kind of leads, on demand. Canonical phrasings: "I want more leads on this lens", "extend the lens", "give me a bigger batch today". The \`leadbay_extend_my_lens\` prompt is the user-facing entry point that orchestrates the whole flow.
 
@@ -9221,6 +9226,8 @@ Pick the row matching the response \`status\`. Seed-picking is internal; do NOT
 | \`quota_exceeded\`        | "Upgrade plan for a higher daily limit"                       | (no call \u2014 direct user to contact account manager / sales) |
 | \`refresh_in_progress\`   | "Lens is already filling \u2014 pull leads in a minute"            | \`leadbay_pull_leads()\` (after a short wait)            |
 | \`no_valid_seeds\`        | (silent retry \u2014 re-call \`leadbay_seed_candidates\` then \`leadbay_extend_lens\`) | internal \u2014 only surface if the second attempt also fails |
+| \`no_candidates\`         | "Widen the audience \u2014 this lens has nothing left to add"       | \`leadbay_adjust_audience()\` \u2014 never \`leadbay_extend_lens\` again |
+| \`no_candidates\` (\`reason.code: no_new_leads\`) | "Work the leads already in the lens"        | \`leadbay_pull_followups()\`                             |
 
 If nothing matches cleanly, default to "pull leads now to see what's queued" \u2014 never invent a tool that doesn't exist.
 `;
@@ -18370,6 +18377,21 @@ function narrowGeoSentence(narrow) {
     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 readAudienceShape(client, lensId) {
+  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);
+  return {
+    ...summary ? { criteria: summary } : {},
+    ...narrow.length > 0 ? { narrow_locations: narrow } : {},
+    geoSentence: narrowGeoSentence(narrow)
+  };
+}
 async function diagnoseEmptyLens(client, lensId, computing) {
   if (computing.wishlist || computing.scores) {
     return {
@@ -18384,19 +18406,8 @@ async function diagnoseEmptyLens(client, lensId, computing) {
     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 } : {}
-  };
+  const { geoSentence: geo, ...extras } = await readAudienceShape(client, lensId);
+  const summary = extras.criteria;
   if (row?.not_enough_lead_candidates) {
     return {
       code: "no_candidates",
@@ -25140,6 +25151,48 @@ async function readExtraRefillQuota(client) {
     return { count: null, resets_at: null };
   }
 }
+async function readAvailablePool(client, lensId) {
+  try {
+    const preview = await client.request("GET", `/lenses/${lensId}/extra_refill_preview`);
+    return typeof preview?.available_count === "number" ? preview.available_count : null;
+  } catch {
+    return null;
+  }
+}
+async function readLensLeadTotal(client, lensId) {
+  try {
+    const page = await client.request("GET", `/lenses/${lensId}/leads/wishlist?count=1&page=0`);
+    return typeof page?.pagination?.total === "number" ? page.pagination.total : null;
+  } catch {
+    return null;
+  }
+}
+function noCandidatesReason(held, shape) {
+  const { geoSentence, ...extras } = shape;
+  const futile = " Extending again is futile \u2014 a refill on a lens with an empty candidate pool reports queued, consumes no quota and delivers nothing.";
+  if (held === 0) {
+    return {
+      code: "audience_too_narrow",
+      retryable: false,
+      message: "This lens holds no leads and has none left to add: its criteria intersect to nothing." + geoSentence + futile + " Tell the user which criteria are in play and offer to widen the audience (leadbay_adjust_audience).",
+      ...extras
+    };
+  }
+  if (held !== null) {
+    return {
+      code: "no_new_leads",
+      retryable: false,
+      message: `Every company matching this lens has already been delivered \u2014 all ${held} of them \u2014 so there is nothing left to add.` + futile + " Tell the user; offer to widen the audience (leadbay_adjust_audience) or work the leads already in the lens (leadbay_pull_followups).",
+      ...extras
+    };
+  }
+  return {
+    code: "no_candidates",
+    retryable: false,
+    message: "This lens has no candidates left to add." + geoSentence + futile + " Tell the user and offer to widen the audience (leadbay_adjust_audience).",
+    ...extras
+  };
+}
 var extendLens = {
   name: "leadbay_extend_lens",
   annotations: {
@@ -25176,7 +25229,7 @@ var extendLens = {
     properties: {
       status: {
         type: "string",
-        description: "queued | quota_exceeded | refresh_in_progress | no_valid_seeds"
+        description: "queued | no_candidates | quota_exceeded | refresh_in_progress | no_valid_seeds"
       },
       lens: {
         type: "object",
@@ -25191,6 +25244,35 @@ var extendLens = {
         type: "string",
         description: "Human-readable summary. On error statuses, this is the line to surface to the user."
       },
+      available_count: {
+        type: ["number", "null"],
+        description: "How many leads a refill on this lens could still draw, read from /extra_refill_preview before queueing. 0 means the refill was NOT queued (status=no_candidates). null means the pool could not be read and the refill was queued anyway."
+      },
+      reason: {
+        type: "object",
+        description: "Only present on status=no_candidates. Same shape and `code` vocabulary as leadbay_pull_leads' empty_reason, so one routing rule covers both tools.",
+        properties: {
+          code: {
+            type: "string",
+            description: "audience_too_narrow (lens holds nothing and its criteria intersect to nothing) | no_new_leads (everything matching has already been delivered) | no_candidates (pool is empty; which of the two could not be determined)"
+          },
+          message: { type: "string" },
+          retryable: {
+            type: "boolean",
+            description: "Always false here. Re-calling leadbay_extend_lens cannot change the outcome \u2014 widen the audience instead."
+          },
+          criteria: {
+            type: "object",
+            description: "The criteria in play, so the agent can name them."
+          },
+          narrow_locations: {
+            type: "array",
+            description: "Include-locations that resolved to city-scale or smaller \u2014 the usual thing to relax first.",
+            items: { type: "object" }
+          }
+        },
+        required: ["code", "message", "retryable"]
+      },
       quota: {
         type: "object",
         description: "Only present on status=quota_exceeded. Shows the org's daily LENS_EXTRA_REFILL state.",
@@ -25204,6 +25286,21 @@ var extendLens = {
   },
   execute: async (client, params) => {
     const lensId = params.lensId ?? await client.resolveDefaultLens();
+    const availableCount = await readAvailablePool(client, lensId);
+    if (availableCount === 0) {
+      const [shape, held] = await Promise.all([
+        readAudienceShape(client, lensId),
+        readLensLeadTotal(client, lensId)
+      ]);
+      const reason = noCandidatesReason(held, shape);
+      return {
+        status: "no_candidates",
+        lens: { id: lensId },
+        available_count: 0,
+        reason,
+        message: reason.message
+      };
+    }
     const body = {
       seed_lead_ids: params.seed_lead_ids ?? []
     };
@@ -25215,6 +25312,7 @@ var extendLens = {
       return {
         status: "queued",
         lens: { id: lensId },
+        available_count: availableCount,
         accepted_seeds: res.accepted_seeds,
         message: "Extra refill queued. Leads stream in asynchronously \u2014 call leadbay_pull_leads in ~30s to see them."
       };
@@ -28441,7 +28539,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.31.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.1" : "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.31.0" : "0.0.0-dev";
+    VERSION = true ? "0.31.1" : "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.31.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.1" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

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