@leadbay/mcp 0.16.2 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog — @leadbay/mcp
 
+## 0.17.0 — 2026-05-29
+
+- **Lens extension** (product#3654): two new composites that expose the
+  backend's agent-driven on-demand lens fill (backend#1844 / api-specs#205).
+  - `leadbay_extend_lens` (write, gated by `LEADBAY_MCP_WRITE=1`) —
+    `POST /lenses/{id}/extra_refill`. Translates the backend's 429
+    `quota_exceeded` / 409 `refresh_in_progress` / 400 `no_valid_seeds`
+    errors into routable `status` envelopes. On 429 the response carries
+    `quota.used_today` + `quota.resets_at` and a message instructing the
+    agent to surface three options to the user (smaller `extra_count` /
+    wait for reset / upgrade plan).
+  - `leadbay_seed_candidates` (read) — internal scaffolding for the
+    extend flow. Returns ranked candidate leads with rich signal
+    (description, sector, tags, qq_answers, engagement). The agent picks
+    3–5 seeds silently and chains to `extend_lens`; the user never
+    reviews the seed list.
+- New prompt `leadbay_extend_my_lens` orchestrates the four-phase flow:
+  quota pre-check → silent seed pick → fire extend → react to status.
+- `leadbay_account_status` description now mentions the per-org daily
+  `LENS_EXTRA_REFILL` quota — pre-check it before calling
+  `leadbay_extend_lens`.
+
 ## 0.16.2 — 2026-05-29
 
 - **Tighter `_triggered_by` description on composite tools.** Live test of

package/dist/bin.js

@@ -12,7 +12,7 @@ import {
   granularWriteTools,
   resolveAgentMemorySummary,
   resolveRegion
-} from "./chunk-3V3EPBLZ.js";
+} from "./chunk-ASAKITU3.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -972,6 +972,7 @@ day's batch", "let's prospect". Do NOT trigger on follow-up phrasings
 ("what should I follow up on", "before my trip") \u2014 those go to
 \`leadbay_followup_check_in\`.
 `, "arguments": [], "expected_calls": ["leadbay_account_status", "leadbay_pull_leads", "leadbay_research_lead_by_id", "leadbay_bulk_qualify_leads", "leadbay_enrich_contacts"], "failure_modes": ["Calls leadbay_report_outreach without explicit user authorization", "Surfaces fewer than 10 leads when more are available, or fails to top up via leadbay_qualify_top_n when the batch is short", `Replaces the canonical pull_leads table layout with prose per row (the per-tool RENDERING block is the structural contract; "Today's nudges" goes above it, not in place of it)`, "Skips the nudge paragraph entirely \u2014 the table alone is fine but adding the nudge is the value-add", "Skips deep research on promising leads (Phase 4) \u2014 the agent must call leadbay_research_lead_by_id on each, not just one", "Triggers contact enrichment without asking the user first (it consumes quota)", "Skips the STOP byproduct and proposes next actions on its own", 'Fires 10 parallel leadbay_research_lead_by_id calls and treats "stream closed" errors as terminal \u2014 must serialize and retry singletons', "Re-pulls leadbay_pull_leads without passing the captured lensId, allowing a backend lens shift to discard the Phase 2 batch", 'Treats a "Request timed out" from leadbay_bulk_qualify_leads as terminal instead of retrying with wait_for_completion:false + qualify_status polling', 'Triggers on a follow-up query (e.g., "leads I should follow up with") that should have routed to `leadbay_followup_check_in` \u2014 the two entry points are different data sources (Discover wishlist vs Monitor view) per \xA71.6'] },
+  leadbay_extend_my_lens: { "name": "leadbay_extend_my_lens", "short_description": "Add more leads to the current lens on demand \u2014 for users whose appetite\nexceeds the standard daily fill. The agent picks seeds silently from\nwhat's already on the lens, fires the extra refill, and surfaces the\nqueue confirmation. The user never reviews the seed list.\n", "arguments": [{ "name": "extra_count", "description": "How many extra leads to add. Optional. Omit to use the backend default.", "required": false }], "expected_calls": ["leadbay_account_status", "leadbay_seed_candidates", "leadbay_extend_lens", "leadbay_pull_leads"], "failure_modes": ["Surfaces the seed candidate list to the user instead of picking silently \u2014 the user asked for MORE LEADS, not a candidate review meeting", "Skips the seeded path and calls `leadbay_extend_lens` with no `seed_lead_ids`, losing the bias signal the recommender needs", "On 429, silently retries instead of surfacing the three options (smaller / wait / upgrade) via `ask_user_input_v0`", "Forgets to pre-check `LENS_EXTRA_REFILL` quota in `leadbay_account_status` and burns a wasted API call", "Skips the post-queue pull-leads suggestion, so the user doesn't see what just got added"] },
   leadbay_followup_check_in: { "name": "leadbay_followup_check_in", "short_description": `Run the canonical follow-up check-in: surface KNOWN leads from the
 Monitor view that need re-engagement today, ranked by AI urgency,
 with the canonical pull_followups table layout. Trigger when the
@@ -999,6 +1000,7 @@ should I follow up on" to "I'll send via lemlist".
 var PROMPT_CATALOG_HEADER = `This server exposes the following workflow prompts via \`prompts/list\` and \`prompts/get\`. Some MCP clients render them as slash commands; if your client does not, you (the agent) should invoke them directly via \`prompts/get\` when the user's request matches one of the triggers described below.`;
 var PROMPT_CATALOG_BULLETS = {
   leadbay_daily_check_in: `- \`leadbay_daily_check_in\`: Run the canonical daily check-in: account state, fresh batch, triage top 10, deep-dive every promising one, offer contact enrichment. The morning DISCOVERY workflow (new leads from the lens wishlist). Trigger on "leadbay leads", "best NEW leads", "what's new today", "show me the day's batch", "let's prospect". Do NOT trigger on follow-up phrasings ("what should I follow up on", "before my trip") \u2014 those go to \`leadbay_followup_check_in\`.`,
+  leadbay_extend_my_lens: `- \`leadbay_extend_my_lens\` (optional args: extra_count): Add more leads to the current lens on demand \u2014 for users whose appetite exceeds the standard daily fill. The agent picks seeds silently from what's already on the lens, fires the extra refill, and surfaces the queue confirmation. The user never reviews the seed list.`,
   leadbay_followup_check_in: `- \`leadbay_followup_check_in\`: Run the canonical follow-up check-in: surface KNOWN leads from the Monitor view that need re-engagement today, ranked by AI urgency, with the canonical pull_followups table layout. Trigger when the user asks "follow up", "already known leads", "leads I haven't contacted", "leads in [city]", "before my trip", "this week", "this month", "what's overdue", "who should I re-engage", or anything that implies pre-existing pipeline context.`,
   leadbay_import_file: `- \`leadbay_import_file\` (optional args: file, instruction): Import a user-supplied CSV/file into Leadbay through five phases with evidence gates \u2014 scan, derive, resolve identities, preserve & commit, then optionally qualify and report. The job is to maximize how many rows the Leadbay system actually ingests and matches.`,
   leadbay_log_outreach: `- \`leadbay_log_outreach\` (required args: lead_id, summary): Log outreach (an email I sent, a call I made, a meeting I had) on a specific lead. Captures verification so the SDR pipeline trusts the entry.`,
@@ -3189,7 +3191,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.16.2";
+var VERSION = "0.17.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -3721,7 +3723,7 @@ async function runLogin(args) {
     }
     try {
       if (pinnedRegion && !allowFallback) {
-        const { REGIONS } = await import("./dist-7XHTMWB2.js");
+        const { REGIONS } = await import("./dist-3NYTS7OH.js");
         const baseUrl = REGIONS[pinnedRegion];
         const c = createClient({ region: pinnedRegion });
         const token = await loginAt(baseUrl, email, password);
@@ -4224,7 +4226,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-7XHTMWB2.js");
+      const { REGIONS } = await import("./dist-3NYTS7OH.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;

package/dist/{chunk-3V3EPBLZ.js → chunk-ASAKITU3.js}

@@ -4960,6 +4960,7 @@ var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "leadbay_campaign_progression",
   "leadbay_create_campaign",
   "leadbay_enrich_titles",
+  "leadbay_extend_lens",
   "leadbay_followups_map",
   "leadbay_import_and_qualify",
   "leadbay_import_leads",
@@ -4977,6 +4978,7 @@ var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "leadbay_research_lead_by_id",
   "leadbay_research_lead_by_name_fuzzy",
   "leadbay_resolve_import_rows",
+  "leadbay_seed_candidates",
   "leadbay_tour_plan"
 ]);
 
@@ -5008,7 +5010,7 @@ prominently if mid-regen.
 
 ---
 
-Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch resources, and whether the org's intelligence is mid-regeneration. Quota windows also hint at the user's consumption pace: heavy recent activity (ai_rescore / web_fetch near their window limits) is a signal that Leadbay will deliver a larger fresh batch next time the user logs back in, since batch size is paced by real consumption.
+Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch / LENS_EXTRA_REFILL resources, and whether the org's intelligence is mid-regeneration. **Pre-check \`LENS_EXTRA_REFILL\` here before calling \`leadbay_extend_lens\`** \u2014 its full requested batch must fit into the remaining daily quota or the call is rejected outright. Quota windows also hint at the user's consumption pace: heavy recent activity (ai_rescore / web_fetch near their window limits) is a signal that Leadbay will deliver a larger fresh batch next time the user logs back in, since batch size is paced by real consumption.
 
 **Top-ups always beat waiting.** When a quota window is hit, the user has two options: wait for the window reset (\`resets_at\` in each quota entry) OR top up AI credits. Top-ups clear the throttle IMMEDIATELY; they are not subject to the same window. When you tell the user about a 429 / quota exhaustion, ALWAYS surface both options \u2014 "wait until <reset>" or "top up now (I can generate the link)" \u2014 and let them pick. Never default-recommend "wait until tomorrow" when a 30-second top-up unblocks the same operation.
 
@@ -5592,6 +5594,102 @@ WHEN NOT TO USE: to enrich a single contact \u2014 that's leadbay_enrich_contact
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
+var leadbay_extend_lens = `## WHEN TO USE
+
+Trigger phrases: "I want more leads on this lens", "extend the lens", "I need a bigger batch today", "fill more leads, I've burned through these", "more leads like the ones in this lens".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "show me today's leads" \u2192 \`leadbay_pull_leads\`; "narrow the audience" \u2192 \`leadbay_adjust_audience\`; "stop showing me X" \u2192 \`leadbay_refine_prompt\`.
+
+Prefer when: user has bigger appetite than the daily lens fill delivers \u2014 additive refill on same criteria
+
+Examples that SHOULD invoke this tool:
+- "Give me more leads on this lens \u2014 I want a bigger batch."
+- "Extend the lens, I've burned through what I had."
+- "Add 30 more leads like the ones in this batch."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Show me today's leads."
+- "Narrow the audience to fintech only."
+- "Which leads should I follow up with this week?"
+
+## RENDER (quick)
+
+\`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 \`ask_user_input_v0\` (smaller
+count / wait until 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.
+
+---
+
+Queue an additive extra-refill on a lens \u2014 more leads on the same criteria, without changing the audience. For users whose daily appetite exceeds what the standard fill delivers. Wraps \`POST /lenses/{lensId}/extra_refill\`. The fill happens asynchronously; new leads stream in over ~30s, observable through \`leadbay_pull_leads\`.
+
+**Mandatory chain \u2014 agent picks seeds silently.** Unless the user has explicitly said "no seeds, just fill it", the agent MUST call \`leadbay_seed_candidates\` FIRST, pick 3\u20135 seed leads using the heuristics in that tool's description, and pass them here as \`seed_lead_ids\`. The seed list is **never shown to the user** \u2014 the user asked for more leads, not a candidate review meeting. The canonical \`leadbay_extend_my_lens\` prompt drives this chain.
+
+**Seeds are optional at the wire level** \u2014 omit or empty array \u2192 backend falls back to default centroid strategies (same behaviour as a normal fill). The response's \`accepted_seeds\` echoes the subset that passed validation. Prefer the seeded path because it gives the recommender a signal beyond the lens centroid (which it already biases on).
+
+**Quota gate.** Each call is charged against the per-org daily \`LENS_EXTRA_REFILL\` quota at pre-flight time (FREEMIUM=0 / TIER1=150 / TIER2=1000). The **full requested batch** must fit \u2014 there is no partial fulfillment. **Pre-check via \`leadbay_account_status\`**: look at \`quota.org.resources[]\` for the \`LENS_EXTRA_REFILL\` entry to see how much was used today and when it resets.
+
+**Status envelope (translated from raw API errors so the agent routes on \`status\`).**
+
+- \`status: "queued"\` \u2014 fill is queued. \`accepted_seeds\` lists IDs that passed validation. NEXT STEP: call \`leadbay_pull_leads\` in ~30s.
+- \`status: "quota_exceeded"\` \u2014 daily LENS_EXTRA_REFILL hit. Response carries \`quota: {used_today, resets_at}\` + a \`message\` to surface. **Render three options via \`ask_user_input_v0\`**: (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.
+
+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.
+
+WHEN NOT TO USE: for daily inbox pulls (\`leadbay_pull_leads\`). Not for audience criteria changes (\`leadbay_adjust_audience\` / \`leadbay_refine_prompt\`). Never call this without seeds unless the user explicitly opted out \u2014 the seeded path produces materially better fill.
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+
+
+---
+
+## NEXT STEPS \u2014 after \`leadbay_extend_lens\`
+
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Pick the row matching the response \`status\`. Seed-picking is internal; do NOT add chips that imply the user reviewed candidates.
+
+| \`status\`                | Suggest                                                       | Calls                                                  |
+|-------------------------|---------------------------------------------------------------|--------------------------------------------------------|
+| \`queued\`                | "Pull leads in ~30s to see the new ones"                      | \`leadbay_pull_leads()\` (after a short wait)            |
+| \`quota_exceeded\`        | "Try with a smaller \`extra_count\`"                            | \`leadbay_extend_lens(extra_count=<smaller>)\`           |
+| \`quota_exceeded\`        | "Wait until the daily quota resets at \`<resets_at>\`"          | (no call \u2014 surface the reset time to the user)         |
+| \`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 |
+
+If nothing matches cleanly, default to "pull leads now to see what's queued" \u2014 never invent a tool that doesn't exist.
+`;
 var leadbay_followups_map = `## WHEN TO USE
 
 Trigger phrases: "I'm going to <city>", "visit in person", "map of leads", "plan my itinerary".
@@ -7389,6 +7487,56 @@ Below the table, a one-liner: \`"Ready: K rows \xB7 Ambiguous: A rows \xB7 Unmat
 | Unmatched rows but websites present    | "Import anyway \u2014 Leadbay will crawl and match later"        | leadbay_import_leads (status check after)              |
 | User wants to skip rows they can't ID  | "Drop unmatched rows and import the rest"                   | leadbay_import_leads (with filtered records)           |
 `;
+var leadbay_seed_candidates = `## WHEN TO USE
+
+Trigger phrases: "(internal) agent decided to extend the lens \u2014 fetch seed candidates".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "show me today's leads" \u2192 \`leadbay_pull_leads\`; "leads I should follow up with" \u2192 \`leadbay_pull_followups\`; "narrow the audience" \u2192 \`leadbay_adjust_audience\`; "stop showing me X" \u2192 \`leadbay_refine_prompt\`.
+
+Prefer when: agent is mid-\`leadbay_extend_my_lens\` flow and needs to pick seeds before calling \`leadbay_extend_lens\`
+
+Examples that SHOULD invoke this tool:
+- "(agent-internal) user asked for more leads \u2014 fetch seeds before calling extend_lens"
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Show me today's leads."
+- "Restrict the audience to fintech only."
+- "Which leads should I follow up with this week?"
+
+## RENDER (quick)
+
+DO NOT RENDER TO THE USER. This is internal data the agent reasons over
+before calling \`leadbay_extend_lens\`. No table, no list of company names,
+no "here are your candidates". The user asked for more leads; surface the
+*outcome* of extend_lens, not the picking step.
+
+---
+
+**INTERNAL TOOL \u2014 do not surface candidates to the user.** The user asked for more leads on the lens (a higher daily appetite than the standard fill delivers), not to manually review candidates. This tool exists so the agent can pick seeds *silently*, then chain to \`leadbay_extend_lens\`. Picking is an agent decision; the user only sees the extend confirmation.
+
+Backed by \`GET /lenses/{lensId}/seed_candidates\`. By construction every lead returned is a valid input to \`extra_refill\` (same eligibility query). Defaults to the user's last-active lens.
+
+**Pick 3\u20135 seeds that represent the *kind* of leads the user wants more of**, using these signals in priority order:
+
+1. **\`engagement\`** (load-bearing) \u2014 \`liked: true\`, \`org_contacts_count > 0\`, and \`prospecting_actions_count > 0\` mean the user (or their team) already validated this lead. These are the strongest signal.
+2. **\`qq_answers\`** \u2014 what the AI agent already answered when qualifying this lead. Match candidates whose answers align with the target profile.
+3. **\`tags\`** \u2014 purchase-intent alignment, ordered by score (most-relevant first).
+4. **\`sector\`, \`size_min\`, \`size_max\`** \u2014 shape similarity to known-good prospects.
+5. **\`ai_agent_score\`** \u2014 overall AI fit (0\u201399); null when the lead has not been AI-rescored.
+6. **\`description\`** \u2014 short company blurb for the final tie-breaker.
+
+**Default heuristic** (no explicit user steering): top 3 by engagement (prefer \`liked: true\`; break ties by \`org_contacts_count + prospecting_actions_count\`), then fill to 5 with the top \`ai_agent_score\` rows whose \`tags\` overlap the engagement leaders' tags.
+
+**Once seeds are picked, call \`leadbay_extend_lens\` immediately with \`seed_lead_ids=[...picked lead_ids]\`.** Do not pause for user approval; the user wants more leads, not a seed-review meeting.
+
+WHEN TO USE: only as the scaffolding step inside an extend-the-lens flow. The \`leadbay_extend_my_lens\` prompt orchestrates this; agents called this tool by themselves should be rare.
+
+WHEN NOT TO USE: when the user wants to CHANGE the audience (sector / size / criteria) \u2014 route to \`leadbay_adjust_audience\` or \`leadbay_refine_prompt\`. Not for the daily inbox pull \u2014 route to \`leadbay_pull_leads\`. Never as a "here are some candidates, which do you want?" user-facing surface.
+
+Response shape (relayed verbatim from the backend): \`{ candidates: [{lead_id, name, description?, sector?, size_min?, size_max?, website?, ai_agent_score?, tags[], qq_answers[], org_lead_status?, engagement: {liked, org_contacts_count, prospecting_actions_count}}] }\`.
+`;
 var leadbay_select_leads = `Add leads to the user's transient selection (used by selection-scoped bulk operations). Accepts 1-1000 \`leadIds\` per call.
 
 WHEN TO USE: low-level. The user's selection is a per-token global state \u2014 be careful when invoking directly.
@@ -13657,7 +13805,7 @@ var accountStatus = {
       },
       quota: {
         type: ["object", "null"],
-        description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch) across daily/weekly/monthly windows. Null if /quota_status failed (logged in stderr)."
+        description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch, LENS_EXTRA_REFILL) across daily/weekly/monthly windows. Null if /quota_status failed (logged in stderr). Pre-check the LENS_EXTRA_REFILL entry before calling leadbay_extend_lens."
       },
       _meta: {
         type: "object",
@@ -17066,6 +17214,182 @@ var refinePrompt = {
   }
 };
 
+// ../core/dist/composite/seed-candidates.js
+var seedCandidates = {
+  name: "leadbay_seed_candidates",
+  annotations: {
+    title: "List candidate seeds for a lens extra-refill",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_seed_candidates,
+  inputSchema: {
+    type: "object",
+    properties: {
+      lensId: {
+        type: "number",
+        description: "Lens to fetch candidates for. Defaults to the user's last-active lens."
+      },
+      limit: {
+        type: "number",
+        description: "Max candidates to return, 1\u201350 (backend default 20)."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      lens: {
+        type: "object",
+        properties: { id: { type: "number" } }
+      },
+      candidates: {
+        type: "array",
+        description: "Ranked candidate leads \u2014 each is a valid seed for leadbay_extend_lens. Pick 3\u20135 that represent the kind of leads the user wants more of.",
+        items: { type: "object" }
+      }
+    },
+    required: ["lens", "candidates"]
+  },
+  execute: async (client, params) => {
+    const lensId = params.lensId ?? await client.resolveDefaultLens();
+    const limit = params.limit != null ? Math.max(1, Math.min(params.limit, 50)) : 20;
+    const res = await client.request("GET", `/lenses/${lensId}/seed_candidates?limit=${limit}`);
+    return {
+      lens: { id: lensId },
+      candidates: res.candidates
+    };
+  }
+};
+
+// ../core/dist/composite/extend-lens.js
+function httpStatus(err) {
+  return err?._meta?.http_status;
+}
+async function readExtraRefillQuota(client) {
+  try {
+    const me = await client.resolveMe();
+    const quota = await client.request("GET", `/organizations/${me.organization.id}/quota_status`);
+    const entry = quota.org?.resources?.find((r) => r.resource_type === "LENS_EXTRA_REFILL");
+    return {
+      count: entry?.count ?? null,
+      resets_at: entry?.resets_at ?? null
+    };
+  } catch {
+    return { count: null, resets_at: null };
+  }
+}
+var extendLens = {
+  name: "leadbay_extend_lens",
+  annotations: {
+    title: "Extend a lens with additional leads (extra refill)",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  description: leadbay_extend_lens,
+  optional: true,
+  // gated behind LEADBAY_MCP_WRITE=1 in MCP
+  inputSchema: {
+    type: "object",
+    properties: {
+      lensId: {
+        type: "number",
+        description: "Lens to extend. Defaults to the user's last-active lens."
+      },
+      seed_lead_ids: {
+        type: "array",
+        description: "Optional list of lead UUIDs from leadbay_seed_candidates to bias the recommender. Omit or empty array \u2192 default-strategy fallback (same behaviour as a normal fill).",
+        items: { type: "string" }
+      },
+      extra_count: {
+        type: "number",
+        description: "How many extra leads to request. Omit to use the backend default. The full requested count must fit into the remaining daily LENS_EXTRA_REFILL quota \u2014 otherwise the call is rejected outright (status: quota_exceeded)."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        description: "queued | quota_exceeded | refresh_in_progress | no_valid_seeds"
+      },
+      lens: {
+        type: "object",
+        properties: { id: { type: "number" } }
+      },
+      accepted_seeds: {
+        type: "array",
+        description: "Subset of seed_lead_ids that passed validation and will bias the fill. Empty when no seeds were submitted (default-strategies fallback). Present only on status=queued.",
+        items: { type: "string" }
+      },
+      message: {
+        type: "string",
+        description: "Human-readable summary. On error statuses, this is the line to surface to the user."
+      },
+      quota: {
+        type: "object",
+        description: "Only present on status=quota_exceeded. Shows the org's daily LENS_EXTRA_REFILL state.",
+        properties: {
+          used_today: { type: ["number", "null"] },
+          resets_at: { type: ["string", "null"] }
+        }
+      }
+    },
+    required: ["status", "lens"]
+  },
+  execute: async (client, params) => {
+    const lensId = params.lensId ?? await client.resolveDefaultLens();
+    const body = {
+      seed_lead_ids: params.seed_lead_ids ?? []
+    };
+    if (params.extra_count != null) {
+      body.extra_count = params.extra_count;
+    }
+    try {
+      const res = await client.request("POST", `/lenses/${lensId}/extra_refill`, body);
+      return {
+        status: "queued",
+        lens: { id: lensId },
+        accepted_seeds: res.accepted_seeds,
+        message: "Extra refill queued. Leads stream in asynchronously \u2014 call leadbay_pull_leads in ~30s to see them."
+      };
+    } catch (err) {
+      const status = httpStatus(err);
+      if (status === 429) {
+        const q = await readExtraRefillQuota(client);
+        return {
+          status: "quota_exceeded",
+          lens: { id: lensId },
+          quota: { used_today: q.count, resets_at: q.resets_at },
+          message: "Daily LENS_EXTRA_REFILL quota exhausted. Surface to user: (1) try a smaller extra_count, (2) wait for the daily reset" + (q.resets_at ? ` (resets at ${q.resets_at})` : "") + ", or (3) upgrade plan for a higher daily limit (TIER1=150, TIER2=1000)."
+        };
+      }
+      if (status === 409) {
+        return {
+          status: "refresh_in_progress",
+          lens: { id: lensId },
+          message: "A refresh or extra-refill is already running on this lens. Wait, then call leadbay_pull_leads in ~30s."
+        };
+      }
+      if (status === 400) {
+        return {
+          status: "no_valid_seeds",
+          lens: { id: lensId },
+          message: "Every submitted seed failed validation (likely stale \u2014 the lens shape may have changed). Refetch via leadbay_seed_candidates and retry."
+        };
+      }
+      throw err;
+    }
+  }
+};
+
 // ../core/dist/composite/answer-clarification.js
 var answerClarification = {
   name: "leadbay_answer_clarification",
@@ -17649,6 +17973,9 @@ var compositeReadTools = [
   qualifyStatus,
   importStatus,
   resolveImportRows,
+  // seed-candidates is a read-only discovery surface for the extend flow.
+  // Always exposed so the agent can show candidates even in read-only deployments.
+  seedCandidates,
   // listMappableFields is granular-shaped but the import composites depend on
   // it for discoverability; expose it always-on so agents can find custom fields
   // without needing LEADBAY_MCP_ADVANCED=1.
@@ -17692,7 +18019,10 @@ var compositeWriteTools = [
   // Backend POST endpoints; gated behind LEADBAY_MCP_WRITE=1 in MCP.
   createCampaign,
   addLeadsToCampaign,
-  removeLeadsFromCampaign
+  removeLeadsFromCampaign,
+  // Lens extend — agent-driven on-demand fill (additive). Gated behind
+  // LEADBAY_MCP_WRITE=1. Subject to per-org daily LENS_EXTRA_REFILL quota.
+  extendLens
 ];
 var compositeTools = [
   ...compositeReadTools,
@@ -17815,6 +18145,8 @@ export {
   bulkEnrichStatus,
   adjustAudience,
   refinePrompt,
+  seedCandidates,
+  extendLens,
   answerClarification,
   reportOutreach,
   reportFriction,

package/dist/{dist-7XHTMWB2.js → dist-3NYTS7OH.js}

@@ -50,6 +50,7 @@ import {
   enrichContacts,
   enrichTitles,
   ensureAgentMemorySummary,
+  extendLens,
   followupsMap,
   formatLoginError,
   getClarification,
@@ -115,6 +116,7 @@ import {
   resolveAgentMemorySummary,
   resolveImportRows,
   resolveRegion,
+  seedCandidates,
   selectLeads,
   setActiveLens,
   setEpilogueStatus,
@@ -125,7 +127,7 @@ import {
   updateLens,
   updateLensFilter,
   withAgentMemoryMeta
-} from "./chunk-3V3EPBLZ.js";
+} from "./chunk-ASAKITU3.js";
 export {
   AgentMemoryCaptureInputSchema,
   AgentMemoryEntrySchema,
@@ -177,6 +179,7 @@ export {
   enrichContacts,
   enrichTitles,
   ensureAgentMemorySummary,
+  extendLens,
   followupsMap,
   formatLoginError,
   getClarification,
@@ -242,6 +245,7 @@ export {
   resolveAgentMemorySummary,
   resolveImportRows,
   resolveRegion,
+  seedCandidates,
   selectLeads,
   setActiveLens,
   setEpilogueStatus,

package/package.json

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