@leadbay/mcp 0.17.3 → 0.18.0

package/dist/http-server.js

@@ -1756,6 +1756,23 @@ var LeadbayClient = class {
     await this.resolveOrgId();
     await this.resolveTasteProfile();
   }
+  // ─── Notifications helpers ────────────────────────────────────────────
+  // Backend exposes `GET /notifications`, `POST /notifications/{id}/seen`,
+  // `POST /notifications/{id}/archive`, plus `GET /ws/ticket?v=1.0` to mint
+  // a one-shot WS URL. See backend/docs/adr/notifications.md for shape.
+  async listNotifications(args = {}) {
+    const params = new URLSearchParams();
+    params.set("archived", String(args.archived ?? false));
+    params.set("page", String(args.page ?? 0));
+    params.set("count", String(args.count ?? 50));
+    return this.request("GET", `/notifications?${params.toString()}`);
+  }
+  async acknowledgeNotification(notificationId, action = "seen") {
+    await this.requestVoid("POST", `/notifications/${notificationId}/${action}`);
+  }
+  async getWsTicket() {
+    return this.request("GET", "/auth/ws?v=1.0");
+  }
   makeError(code, message, hint, endpoint, retry_after, http_status) {
     const out = { error: true, code, message, hint };
     if (endpoint || this._region) {
@@ -6205,6 +6222,9 @@ var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "leadbay_tour_plan"
 ]);
 
+// ../core/dist/notifications/inbox.js
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+
 // ../core/dist/tool-descriptions.generated.js
 var leadbay_account_status = `## WHEN TO USE
 
@@ -6241,10 +6261,53 @@ Show the user's account state \u2014 admin rights, language, last-active lens, c
 
 **After a user tops up, do NOT keep refusing \u2014 RETRY.** If the user signals they topped up / bought credits / added credits, the previous QUOTA_EXCEEDED is invalidated the moment the Stripe webhook lands. RE-CALL \`leadbay_account_status\` to pick up the new state AND retry the originally failed call. The retry itself does not require a successful account_status check first \u2014 a topped-up user has cleared the throttle whether or not your cached snapshot reflects it yet. If the retry hits the wall again, only then re-offer top-up / wait. **A stale quota snapshot is never a reason to gate-keep a topped-up user.**
 
+**\`notifications\` block.** The response now includes a top-level \`notifications\` array listing background work the user (or agent) initiated that has since completed (\`bulk_enrich\`, \`bulk_qualify\`, \`import\`). These are signals to revise prior agent outputs the just-finished work might have made stale \u2014 they're NOT a pending-task list for the user. After revising (or confirming nothing is affected), call \`leadbay_acknowledge_notification(notification_id)\`. Full handling protocol below.
+
+## GATE \u2014 INSPECT \`_meta.notifications\` ON EVERY RESPONSE
+
+Some Leadbay tool responses include a \`_meta.notifications\` array listing **background work the user (or you) initiated that has since completed**. The three relevant kinds:
+
+| Kind | What just finished |
+|---|---|
+| \`bulk_enrich\` | A bulk contact-enrichment job (emails / phone numbers attached to leads' contacts). |
+| \`bulk_qualify\` | A bulk lead-qualification job (web-fetch + AI rescore, producing \`ai_agent_lead_score\` and qualification answers). |
+| \`import\` | A CSV / CRM file import (rows resolved to leads in the user's pipeline). |
+
+**Your job when you see an entry: revise prior outputs the just-finished work might have made stale.** This is NOT a pending-task list. It's a "your earlier answer used data that has now changed" signal.
+
+| Kind | Outputs you've produced that may now be stale \u2014 refresh them |
+|---|---|
+| \`bulk_enrich\` | Outreach drafts mentioning these leads' contacts; contact lists; recommended-lead lists citing \`contact_count\`; NEXT STEPS that asked the user to wait for emails / phones. Re-fetch via \`leadbay_get_contacts(leadId)\` for the affected leads. |
+| \`bulk_qualify\` | Lead rankings / shortlists you produced without \`ai_agent_lead_score\`; "today's leads"; followup maps; prepare-outreach picks. Re-pull via \`leadbay_pull_leads\` / \`leadbay_research_lead_by_id\`. |
+| \`import\` | "Available leads" claims; pulls from the affected lens that ran before the import landed; followup planning that needed the imported set. Re-pull via \`leadbay_pull_leads\` / \`leadbay_pull_followups\`. |
+
+**After revising (or after confirming no prior output is affected):** call \`leadbay_acknowledge_notification(notification_id)\` so the entry stops resurfacing on every tool response. Ack-and-move-on is correct even when nothing was stale \u2014 that's how the inbox stays focused on what's actually pending.
+
+**Do NOT** interpret these entries as "things waiting for the user." The user expects you to handle them silently. They are signals to YOU \u2014 agent \u2014 that prior outputs need a refresh.
+
+**Don't poll.** When you launch a long operation (enrichment / qualification / import), simply continue the conversation \u2014 the next time you call any tool, the completed-work entry will appear in \`_meta.notifications\`. Status tools (\`leadbay_bulk_enrich_status\`, \`leadbay_qualify_status\`, \`leadbay_import_status\`) exist for the case where you want the answer NOW (mid-conversation), not for ambient polling.
+
+Also surfaced as a top-level \`notifications\` array on \`leadbay_account_status\` \u2014 same shape, same handling.
+
+
 WHEN TO USE: at the start of a session to know what the agent can/can't do, after a 429 to explain to the user which resource window was exhausted and when it resets (and to offer the top-up alternative), and after the user signals a top-up so the agent can resume the interrupted workflow.
 
 WHEN NOT TO USE: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating. And: a recent quota snapshot showing "exhausted" is NOT a reason to refuse a write call when the user has just topped up \u2014 re-call this tool first, then proceed.
 `;
+var leadbay_acknowledge_notification = `Acknowledge a Leadbay notification \u2014 i.e. tell the MCP and the backend "I've seen this and acted on it." Wraps \`POST /1.5/notifications/{id}/seen\` (default) or \`/archive\` (when \`archive:true\`) and drops the entry from the local inbox so subsequent \`_meta.notifications\` payloads stop carrying it.
+
+**When to call.** After you read an entry from \`_meta.notifications\` or \`account_status.notifications\` and have revised whatever prior output the just-finished background work might have made stale (outreach drafts, lead lists, "available leads" claims, followup plans). Mark-seen tells the human team's pipeline you handled this and prevents the notification from re-surfacing on every subsequent tool response.
+
+If nothing you produced for the user is affected, ack anyway with \`archive:false\` \u2014 the entry should still clear so the inbox stays focused on what's actually pending.
+
+Use \`archive:true\` only when you want the row gone from the FE notification dropdown too (e.g. a non-actionable system notification that's already handled). Default behaviour is \`seen\` \u2014 same as the FE dropdown's "click to read" semantics.
+
+WHEN TO USE: immediately after you finish reviewing / revising in response to a \`_meta.notifications[]\` entry. Idempotent \u2014 calling twice with the same id is safe.
+
+WHEN NOT TO USE: before doing the revision work; for general "mark all read" sweeps (call once per notification id you've actually consumed).
+
+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_add_leads_to_campaign = `## WHEN TO USE
 
 Trigger phrases: "add leads to <name> campaign", "attach these to <campaign>", "put these in Q2 Push", "add to existing campaign".
@@ -11148,9 +11211,23 @@ async function completeUploadedChunk(client, upload, mappings, dryRun, perPhaseB
   await pollPreprocess(client, importId, phaseBudget, ctx, signal);
   ctx?.logger?.info?.(`import-leads: preprocess done for importId=${importId}`);
   if (dryRun) {
-    return { importId, records: [] };
+    return { importId, records: [], notification_id: null };
+  }
+  let updateMappingsResp = null;
+  try {
+    updateMappingsResp = await client.request("POST", `/imports/${importId}/update_mappings`, mappings);
+  } catch (err) {
+    if (err?.code === "API_ERROR" || err?.code === "NOT_FOUND") {
+      ctx?.logger?.warn?.(`import-leads: update_mappings raw error (${err?.code}); retrying void`);
+      await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
+    } else {
+      throw err;
+    }
+  }
+  const importNotificationId = updateMappingsResp?.notification_id ?? null;
+  if (importNotificationId) {
+    ctx?.logger?.info?.(`import-leads: notification_id=${importNotificationId} importId=${importId}`);
   }
-  await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
   ctx?.logger?.info?.(`import-leads: mappings committed for importId=${importId}`);
   const phaseBudget2 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
   await pollProcess(client, importId, phaseBudget2, ctx, signal);
@@ -11158,7 +11235,7 @@ async function completeUploadedChunk(client, upload, mappings, dryRun, perPhaseB
   const phaseBudget3 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
   const records = await pollRecordsToTerminal(client, importId, phaseBudget3, chunk.length, ctx, signal);
   ctx?.logger?.info?.(`import-leads: ${records.length} records terminal for importId=${importId}`);
-  return { importId, records };
+  return { importId, records, notification_id: importNotificationId };
 }
 function reconcileOneChunk(prep, chunk, matched, notImported) {
   const seenInputIndex = /* @__PURE__ */ new Set();
@@ -11214,7 +11291,7 @@ function reconcileOneChunk(prep, chunk, matched, notImported) {
     }
   }
 }
-function buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled) {
+function buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds) {
   const leads = [];
   const not_imported = [];
   if (dryRun) {
@@ -11279,6 +11356,7 @@ function buildImportLeadsResult(client, prep, importIds, matched, notImported, d
     leads,
     not_imported,
     importIds,
+    notification_ids: notificationIds,
     region: client.region,
     cancelled: cancelled || void 0,
     dry_run: dryRun || void 0,
@@ -11466,6 +11544,7 @@ var importLeads = {
         leads: [],
         not_imported,
         importIds: [],
+        notification_ids: [],
         region: client.region,
         dry_run: dryRun || void 0,
         _meta: client.lastMeta ?? {
@@ -11520,6 +11599,10 @@ var importLeads = {
         status: "running",
         handle_id: reservation.record.bulk_id,
         importIds: importIds2,
+        // Notifications fire from update_mappings, which the background
+        // task hasn't called yet at this point. They surface via the WS
+        // listener / catch-up REST on subsequent agent turns.
+        notification_ids: [],
         progress: {
           phase: reservation.record.status === "complete" ? "complete" : importIds2.length > 0 ? "preprocess" : "queued",
           records_processed: reservation.record.status === "complete" ? reservation.record.records_total : 0,
@@ -11540,6 +11623,7 @@ var importLeads = {
     }
     ctx?.logger?.info?.(`import-leads(${prep.mode}): ${prep.validInputs.length} rows \u2192 ${chunks.length} chunk(s); dry_run=${dryRun}, totalBudgetMs=${totalBudget}`);
     const importIds = [];
+    const notificationIds = [];
     const matched = /* @__PURE__ */ new Map();
     const notImported = /* @__PURE__ */ new Map();
     let cancelled = false;
@@ -11551,6 +11635,9 @@ var importLeads = {
       for (let i = 0; i < chunks.length; i++) {
         const chunk = chunks[i];
         const out = await runOneChunk(client, chunk, i, chunks.length, prep.header, prep.mappings, dryRun, perPhaseBudget, totalDeadline, ctx, signal, recordImportId);
+        if (out.notification_id && !notificationIds.includes(out.notification_id)) {
+          notificationIds.push(out.notification_id);
+        }
         if (!dryRun) {
           reconcileOneChunk(prep, out, matched, notImported);
         }
@@ -11571,7 +11658,7 @@ var importLeads = {
         throw err;
       }
     }
-    return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled);
+    return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds);
   }
 };
 async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, handleId) {
@@ -11588,17 +11675,21 @@ async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, ha
     void (async () => {
       const bgCtx = { logger: ctx.logger, bulkTracker: tracker };
       const importIds = uploadedChunks.map((chunk) => chunk.importId);
+      const notificationIds = [];
       const matched = /* @__PURE__ */ new Map();
       const notImported = /* @__PURE__ */ new Map();
       try {
         const totalDeadline = Date.now() + opts.totalBudget;
         for (const upload of uploadedChunks) {
           const out = await completeUploadedChunk(client, upload, prep.mappings, opts.dryRun, opts.perPhaseBudget, totalDeadline, bgCtx, void 0);
+          if (out.notification_id && !notificationIds.includes(out.notification_id)) {
+            notificationIds.push(out.notification_id);
+          }
           if (!opts.dryRun) {
             reconcileOneChunk(prep, out, matched, notImported);
           }
         }
-        const result = buildImportLeadsResult(client, prep, importIds, matched, notImported, opts.dryRun, false);
+        const result = buildImportLeadsResult(client, prep, importIds, matched, notImported, opts.dryRun, false, notificationIds);
         await tracker.markImportComplete(handleId, {
           leads: result.leads,
           not_imported: result.not_imported,
@@ -12266,6 +12357,63 @@ var agentMemoryReview = {
   }
 };
 
+// ../core/dist/tools/acknowledge-notification.js
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var acknowledgeNotification = {
+  name: "leadbay_acknowledge_notification",
+  annotations: {
+    title: "Acknowledge a Leadbay notification",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_acknowledge_notification,
+  write: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      notification_id: {
+        type: "string",
+        description: "UUID of the notification to acknowledge. Use the notification_id from `_meta.notifications[]` or `account_status.notifications[]`."
+      },
+      archive: {
+        type: "boolean",
+        description: "If true, archive the notification (won't appear in `archived=false` listings). If false / omitted, mark seen (resets firstSeenAt)."
+      }
+    },
+    required: ["notification_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      acknowledged: { type: "boolean" },
+      notification_id: { type: "string" },
+      action: { type: "string", enum: ["seen", "archive"] }
+    },
+    required: ["acknowledged", "notification_id", "action"]
+  },
+  execute: async (client, params, ctx) => {
+    if (!UUID_RE.test(params.notification_id)) {
+      return {
+        error: true,
+        code: "BAD_INPUT",
+        message: "notification_id must be a UUID",
+        hint: "Pass the notification_id verbatim from _meta.notifications[].notification_id or account_status.notifications[].notification_id."
+      };
+    }
+    const action = params.archive ? "archive" : "seen";
+    await client.acknowledgeNotification(params.notification_id, action);
+    ctx?.notificationsInbox?.markSeen(params.notification_id);
+    return {
+      acknowledged: true,
+      notification_id: params.notification_id,
+      action
+    };
+  }
+};
+
 // ../core/dist/tools/select-leads.js
 var selectLeads = {
   name: "leadbay_select_leads",
@@ -15338,6 +15486,11 @@ var accountStatus = {
         type: ["object", "null"],
         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."
       },
+      notifications: {
+        type: "array",
+        description: "Terminal bulk-progress notifications the MCP knows about (background work the user or agent started that has since completed). Each entry carries notification_id, kind (bulk_enrich | bulk_qualify | import | other), bulk_progress counters, and a revise_hint pointing at prior agent outputs the just-finished work might have made stale. After revising affected outputs, call leadbay_acknowledge_notification(notification_id) to clear the entry. Empty array when nothing has completed.",
+        items: { type: "object" }
+      },
       _meta: {
         type: "object",
         properties: {
@@ -15397,6 +15550,13 @@ var accountStatus = {
       // on /me are intentionally NOT surfaced — they're defunct (see
       // SHAPE-DRIFT.md probe round 4).
       quota,
+      // Inbox of terminal bulk-progress notifications. Same shape the MCP
+      // server attaches to `_meta.notifications` on every tool response —
+      // duplicated here as a top-level field so the agent's daily-rhythm
+      // check-in (this composite) sees them without having to read _meta.
+      // Empty array when the WS listener isn't wired (OpenClaw, tests) OR
+      // when nothing has completed since the last ack.
+      notifications: ctx?.notificationsInbox?.list() ?? [],
       _meta: {
         region: client.region
       }
@@ -15410,6 +15570,33 @@ var DEFAULT_COUNT = 10;
 var MAX_COUNT = 25;
 var DEFAULT_PER_LEAD_BUDGET_MS = 9e4;
 var DEFAULT_TOTAL_BUDGET_MS2 = 5 * 6e4;
+async function launchBulkQualify(client, leadIds, ctx) {
+  await client.acquireSelectionLock();
+  try {
+    try {
+      const qs = leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
+      await client.requestVoid("POST", `/leads/selection/select?${qs}`);
+      try {
+        const resp = await client.request("POST", "/leads/selection/web_fetch?force_fetch=false", {});
+        return { resp, quotaExceeded: false };
+      } catch (err) {
+        if (err?.code === "QUOTA_EXCEEDED") {
+          ctx?.logger?.warn?.("bulk_qualify_leads: 429 on bulk /leads/selection/web_fetch \u2014 no leads queued");
+          return { resp: null, quotaExceeded: true };
+        }
+        throw err;
+      }
+    } finally {
+      try {
+        await client.requestVoid("POST", "/leads/selection/clear");
+      } catch (e) {
+        ctx?.logger?.warn?.(`bulk_qualify_leads: selection.clear failed: ${e?.message ?? e?.code}`);
+      }
+    }
+  } finally {
+    client.releaseSelectionLock();
+  }
+}
 var bulkQualifyLeads = {
   name: "leadbay_bulk_qualify_leads",
   annotations: {
@@ -15577,69 +15764,50 @@ var bulkQualifyLeads = {
         per_lead_budget_ms: perLeadBudget,
         total_budget_ms: totalBudget
       });
-      const launched2 = [];
-      const failed2 = [];
+      let launchedCount = 0;
+      let notificationId = null;
       let quotaExceeded2 = false;
+      let failed2 = [];
       if (!reservation.reused) {
-        for (const leadId of candidates) {
-          if (quotaExceeded2)
-            break;
-          try {
-            await client.requestVoid("POST", `/leads/${leadId}/web_fetch?force_fetch=false`);
-            launched2.push(leadId);
-          } catch (err) {
-            if (err?.code === "QUOTA_EXCEEDED") {
-              quotaExceeded2 = true;
-            } else if (err?.code === "NOT_FOUND") {
-              failed2.push({ lead_id: leadId, error: "lead not found" });
-            } else {
-              failed2.push({
-                lead_id: leadId,
-                error: err?.message ?? err?.code ?? "unknown"
-              });
-            }
-          }
-        }
-        if (failed2.length === candidates.length || launched2.length > 0 || quotaExceeded2) {
-          await ctx.bulkTracker.markLaunched(reservation.record.bulk_id);
+        const launch = await launchBulkQualify(client, candidates, ctx);
+        quotaExceeded2 = launch.quotaExceeded;
+        notificationId = launch.resp?.notification_id ?? null;
+        const queuedIds = launch.resp?.queued_ids ?? [];
+        const skippedIds = launch.resp?.skipped_ids ?? [];
+        launchedCount = queuedIds.length;
+        const seen = /* @__PURE__ */ new Set([...queuedIds, ...skippedIds]);
+        failed2 = candidates.filter((id) => !seen.has(id)).map((id) => ({ lead_id: id, error: "not_queued" }));
+        if (queuedIds.length > 0 || quotaExceeded2 || skippedIds.length > 0 || failed2.length === candidates.length) {
+          await ctx.bulkTracker.markLaunched(reservation.record.bulk_id, notificationId);
         }
+      } else {
+        notificationId = reservation.record.notification_id ?? null;
+        launchedCount = reservation.record.lead_ids.length;
       }
       const out = {
         status: "running",
         handle_id: reservation.record.bulk_id,
         qualify_id: reservation.record.bulk_id,
         lead_ids: candidates,
-        launched_count: reservation.reused ? reservation.record.lead_ids.length : launched2.length,
+        launched_count: launchedCount,
         failed: failed2,
         quota_exceeded: quotaExceeded2,
         lens_id: lensId,
+        notification_id: notificationId,
         _meta: { region: client.region }
       };
       return out;
     }
-    const launched = [];
-    const failed = [];
-    let quotaExceeded = false;
-    for (const leadId of candidates) {
-      if (quotaExceeded)
-        break;
-      try {
-        await client.requestVoid("POST", `/leads/${leadId}/web_fetch?force_fetch=false`);
-        launched.push(leadId);
-      } catch (err) {
-        if (err?.code === "QUOTA_EXCEEDED") {
-          quotaExceeded = true;
-          ctx?.logger?.warn?.(`bulk_qualify_leads: 429 mid-fanout after launching ${launched.length}/${candidates.length} \u2014 stopping further launches but polling those already in flight`);
-        } else if (err?.code === "NOT_FOUND") {
-          failed.push({ lead_id: leadId, error: "lead not found" });
-        } else {
-          failed.push({
-            lead_id: leadId,
-            error: err?.message ?? err?.code ?? "unknown"
-          });
-        }
-      }
+    const inlineLaunch = await launchBulkQualify(client, candidates, ctx);
+    const quotaExceeded = inlineLaunch.quotaExceeded;
+    const launched = inlineLaunch.resp?.queued_ids ?? [];
+    const inlineSkipped = inlineLaunch.resp?.skipped_ids ?? [];
+    const inlineNotificationId = inlineLaunch.resp?.notification_id ?? null;
+    if (inlineNotificationId) {
+      ctx?.logger?.info?.(`bulk_qualify_leads: launched bulk progress_notification_id=${inlineNotificationId} queued=${launched.length} skipped=${inlineSkipped.length}`);
     }
+    const inlineFailedSeen = /* @__PURE__ */ new Set([...launched, ...inlineSkipped]);
+    const failed = candidates.filter((id) => !inlineFailedSeen.has(id)).map((id) => ({ lead_id: id, error: "not_queued" }));
     let progressDone = 0;
     const progressTotal = launched.length;
     if (progressTotal > 0) {
@@ -16352,6 +16520,7 @@ var importAndQualify = {
           ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
           qualify_id: null,
           import_ids: queued.importIds,
+          notification_ids: queued.notification_ids ?? [],
           imported: queued.leads.map((l) => ({
             leadId: l.leadId,
             ...l.domain ? { domain: l.domain } : {},
@@ -16376,6 +16545,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: queued.importIds,
+        notification_ids: queued.notification_ids ?? [],
         imported: [],
         not_imported: [],
         qualified: [],
@@ -16413,6 +16583,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: importResult.importIds,
+        notification_ids: importResult.notification_ids ?? [],
         imported: [],
         not_imported: importResult.not_imported.map(toNotImportedEntry),
         qualified: [],
@@ -16450,6 +16621,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: importResult.importIds,
+        notification_ids: importResult.notification_ids ?? [],
         imported,
         not_imported,
         qualified: [],
@@ -16560,6 +16732,7 @@ var importAndQualify = {
       ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
       qualify_id: reservation.record.bulk_id,
       import_ids: importResult.importIds,
+      notification_ids: importResult.notification_ids ?? [],
       imported,
       not_imported,
       qualified,
@@ -16901,6 +17074,14 @@ var importStatus = {
 };
 
 // ../core/dist/composite/qualify-status.js
+async function readNotification(client, notificationId) {
+  try {
+    const page = await client.listNotifications({ archived: false, count: 50 });
+    return page.items.find((n) => n.id === notificationId) ?? null;
+  } catch {
+    return null;
+  }
+}
 var qualifyStatus = {
   name: "leadbay_qualify_status",
   annotations: {
@@ -17055,6 +17236,16 @@ var qualifyStatus = {
       const { _stillRunning, _failedCode, ...rest } = r;
       qualified.push(rest);
     }
+    let bulkProgress = null;
+    let inProgressFlag = null;
+    const notifId = record.notification_id ?? null;
+    if (notifId) {
+      const n = await readNotification(client, notifId);
+      if (n) {
+        bulkProgress = n.bulk_progress;
+        inProgressFlag = n.in_progress;
+      }
+    }
     const out = {
       qualify_id: record.bulk_id,
       launched_at: record.launched_at,
@@ -17066,6 +17257,9 @@ var qualifyStatus = {
       still_running,
       failed,
       not_in_lens: [...notInLensSet],
+      notification_id: notifId,
+      bulk_progress: bulkProgress,
+      in_progress: inProgressFlag,
       region: client.region,
       _meta: client.lastMeta ?? {
         region: client.region,
@@ -17078,6 +17272,9 @@ var qualifyStatus = {
       out.per_lead_budget_ms = record.per_lead_budget_ms;
     if (record.total_budget_ms !== void 0)
       out.total_budget_ms = record.total_budget_ms;
+    if (bulkProgress && bulkProgress.quota_hit_count > 0) {
+      out.quota_hit_hint = "Some leads hit the AI-credits quota during qualification. Top up via leadbay_create_topup_link to clear the throttle immediately, or wait until the daily/weekly window resets.";
+    }
     return out;
   }
 };
@@ -17348,6 +17545,7 @@ var enrichTitles = {
               bulk_id: res.record.bulk_id,
               launched_at: res.record.launched_at,
               durability: res.record.durability,
+              notification_id: res.record.notification_id ?? null,
               seconds_since_original_launch: bulkSecondsSinceOriginal ?? 0,
               titles: params.titles,
               email,
@@ -17363,8 +17561,9 @@ var enrichTitles = {
           total: 3,
           message: `Launching enrichment for ${params.titles.length} title${params.titles.length === 1 ? "" : "s"}\u2026`
         });
+        let launchResp = null;
         try {
-          await client.requestVoid("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
+          launchResp = await client.request("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
         } catch (err) {
           const aborted = err?.name === "AbortError" || ctx?.signal?.aborted === true;
           if (bulkRecord && tracker) {
@@ -17388,9 +17587,10 @@ var enrichTitles = {
           }
           throw err;
         }
+        const notificationId = launchResp?.notification_id ?? null;
         if (bulkRecord && tracker) {
           try {
-            await tracker.markLaunched(bulkRecord.bulk_id);
+            await tracker.markLaunched(bulkRecord.bulk_id, notificationId);
           } catch (e) {
             ctx?.logger?.warn?.(`enrich_titles: tracker.markLaunched failed: ${e?.message ?? e}`);
             return {
@@ -17418,8 +17618,9 @@ var enrichTitles = {
           bulk_id: bulkRecord?.bulk_id,
           launched_at: bulkRecord?.launched_at,
           durability: bulkRecord?.durability,
-          message: bulkRecord ? "Enrichment job launched. Backend has no server-side bulk_id yet; MCP minted a client-side bulk_id (persisted to disk by default) so you can poll via leadbay_bulk_enrich_status." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
-          next_action: bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
+          notification_id: notificationId,
+          message: notificationId ? "Enrichment job launched. The MCP is now listening for the backend notification \u2014 when enrichment finishes, a `_meta.notifications` entry will surface on your next tool response (also visible in `leadbay_account_status.notifications`)." : bulkRecord ? "Enrichment job launched. Backend did not return a notification id this time; poll via leadbay_bulk_enrich_status with the bulk_id." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
+          next_action: notificationId ? "Wait for the next `_meta.notifications` entry (typically <2 min for a small batch). If you want progress sooner, call leadbay_bulk_enrich_status({bulk_id})." : bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
         };
       } finally {
         try {
@@ -17435,6 +17636,14 @@ var enrichTitles = {
 };
 
 // ../core/dist/composite/bulk-enrich-status.js
+async function readNotification2(client, notificationId) {
+  try {
+    const page = await client.listNotifications({ archived: false, count: 50 });
+    return page.items.find((n) => n.id === notificationId) ?? null;
+  } catch {
+    return null;
+  }
+}
 var STATUS_FETCH_CONCURRENCY = 5;
 async function pMap(items, fn, concurrency) {
   const out = new Array(items.length);
@@ -17599,6 +17808,53 @@ var bulkEnrichStatus = {
         launched_at: record.launched_at
       };
     }
+    const notifId = record.notification_id ?? null;
+    if (notifId) {
+      const n = await readNotification2(client, notifId);
+      if (n && n.bulk_progress) {
+        const bp = n.bulk_progress;
+        const inProgress = n.in_progress;
+        let leads2 = [];
+        if (!inProgress && includeContacts) {
+          leads2 = await pMap(record.lead_ids, async (leadId) => {
+            try {
+              const out = await getContacts.execute(client, { leadId });
+              const contacts = Array.isArray(out?.contacts) ? out.contacts : [];
+              return { lead_id: leadId, contacts };
+            } catch {
+              return { lead_id: leadId };
+            }
+          }, STATUS_FETCH_CONCURRENCY);
+        } else {
+          leads2 = record.lead_ids.map((id) => ({ lead_id: id }));
+        }
+        ctx?.logger?.info?.(`bulk.status_checked_via_notification bulk_id=${record.bulk_id} notification_id=${notifId} done=${bp.success_count}/${bp.total_count} in_progress=${inProgress} wall_ms=${Date.now() - startMs}`);
+        return {
+          bulk_id: record.bulk_id,
+          notification_id: notifId,
+          launched_at: record.launched_at,
+          status: record.status,
+          durability: record.durability,
+          titles: record.titles,
+          email: record.email,
+          phone: record.phone,
+          lens_id: record.lens_id,
+          leads: leads2,
+          overall_progress: {
+            done: bp.success_count + bp.failure_count + bp.quota_hit_count,
+            total: bp.total_count,
+            done_ratio: bp.total_count === 0 ? 0 : (bp.success_count + bp.failure_count + bp.quota_hit_count) / bp.total_count
+          },
+          bulk_progress: bp,
+          in_progress: inProgress,
+          all_done: !inProgress,
+          ...bp.quota_hit_count > 0 ? {
+            quota_hit_hint: "Some contacts could not be enriched because the AI-credits quota was hit. Top up via leadbay_create_topup_link or wait for the window reset."
+          } : {}
+        };
+      }
+      ctx?.logger?.info?.(`bulk_enrich_status: notification ${notifId} not yet visible; falling back to per-lead fan-out`);
+    }
     let doneSoFar = 0;
     const totalLeads = record.lead_ids.length;
     const results = await pMap(record.lead_ids, async (leadId) => {
@@ -19392,7 +19648,13 @@ var compositeReadTools = [
   // didn't deliver"). Does not mutate Leadbay state; emits a PostHog
   // event only. Companion to leadbay_report_outreach (which DOES write
   // to the backend and stays gated behind LEADBAY_MCP_WRITE).
-  reportFriction
+  reportFriction,
+  // Notification ack — ALWAYS exposed even though it POSTs to /seen.
+  // _meta.notifications surfaces terminal bulk-progress notifications on
+  // every tool response regardless of write gating; without ack the agent
+  // sees the same entries on every call forever. Pairing the surfacing
+  // channel with the clearing tool is non-optional.
+  acknowledgeNotification
 ];
 var compositeWriteTools = [
   bulkQualifyLeads,
@@ -20211,6 +20473,22 @@ function buildServer(client, opts = {}) {
       });
     }
   };
+  const maybeAttachNotifications = (result) => {
+    const inbox = opts.notificationsInbox;
+    if (!inbox) return;
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+      return;
+    }
+    const entries = inbox.list();
+    if (entries.length === 0) return;
+    const envelope = result;
+    const target = envelope.__markdown_envelope === true && envelope.structured !== null && typeof envelope.structured === "object" && !Array.isArray(envelope.structured) ? envelope.structured : envelope;
+    const existingMeta = target._meta && typeof target._meta === "object" && !Array.isArray(target._meta) ? target._meta : {};
+    target._meta = {
+      ...existingMeta,
+      notifications: entries
+    };
+  };
   const isLeadbayBusinessError = (err) => err != null && typeof err === "object" && err.error === true && typeof err.code === "string";
   const buildBusinessCtx = (toolName, envelope, triggered_by) => {
     const meta = envelope._meta ?? {};
@@ -20330,11 +20608,13 @@ function buildServer(client, opts = {}) {
       const result = await tool.execute(client, args, {
         logger: opts.logger,
         bulkTracker: opts.bulkTracker,
+        notificationsInbox: opts.notificationsInbox,
         signal: extra.signal,
         progress,
         elicit
       });
       maybeAttachUpdate(name, result);
+      maybeAttachNotifications(result);
       if (result && typeof result === "object" && result.error === true) {
         const envText = formatErrorForLLM(result);
         const envDur = Date.now() - callStart;
@@ -20629,7 +20909,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.17.3" : "0.0.0-dev";
+var VERSION = true ? "0.18.0" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var sseSessions = /* @__PURE__ */ new Map();