@leadbay/mcp 0.21.0 → 0.21.2

package/dist/http-server.js

@@ -606,6 +606,49 @@ After your first \`leadbay_pull_leads\` call, capture \`response.lens.id\` (the
 
 You don't need to memorize every tool here \u2014 each tool's own description carries a RENDERING block (how to present the response) and a NEXT STEPS block (observation \u2192 suggestion table). Read the relevant tool's description in full when the user picks an entry point. This overview just gets you to the right starting tool.
 
+## Proposing a next step \u2014 only when it genuinely helps
+
+After reporting account state, you MAY propose a concrete next step \u2014 but only when one is genuinely useful, not by reflex. A reflexive "want me to also\u2026?" on every turn is noise; the user notices and it erodes trust.
+
+**Propose a next step when** the overview surfaced an obvious unfinished thread or a blocker the user would want resolved \u2014 a fresh discovery batch waiting, follow-ups due today, or a quota/auth blocker with a specific unblock action. In those cases the next move is real and worth offering.
+
+**Skip it when** there's no clear unfinished thread, the user only wanted the status (a bare "where do I stand?"), or the work they asked for is plainly done. A status read that ends cleanly is a complete answer \u2014 don't manufacture a next step just to have one.
+
+**Lean on memory.** Check the \`_meta.agent_memory.summary\` for prior signal on how this user reacts to next-step offers. If the memory shows they routinely dismiss them, default to NOT proposing (let them ask). If they routinely act on them, lean toward proposing. When the user dismisses or accepts a proposal this turn, that's a material signal \u2014 call \`leadbay_agent_memory_capture\` (\`source:"inferred"\`, low confidence) so the preference compounds across sessions.
+
+**When you do propose, the proposal IS a native choice dialog \u2014 never a prose "let me know if\u2026".** Route 2\u20134 mutually-exclusive next moves into your host's next-step widget (\`ask_user_input_v0\` on Claude chat / ChatGPT, \`AskUserQuestion\` on Claude cowork / Claude Code). The widget is the question; do not also list the same options as prose.
+
+**ALWAYS render NEXT STEPS via your host's next-step widget.** Use whichever is in your tool set \u2014 the NAME and SCHEMA differ: **\`ask_user_input_v0\`** (Claude chat / ChatGPT) takes plain-string options with \`type:"single_select"\`; **\`AskUserQuestion\`** (Claude cowork / Claude Code) takes object options \`{label, description}\` plus a required short \`header\` (\u226412 chars) and \`multiSelect\`, NO \`type\` field, and never add an "Other" option (the host adds it). Match the schema to the tool you actually have \u2014 the wrong schema fails silently and you fall back to prose. Prose bullets are the fallback ONLY when NEITHER widget exists. Any turn that would end with a choice must be the widget \u2014 the widget IS the question.
+
+**If the tool result carries a \`next_steps\` object, that is the source of truth \u2014 use it directly.** Each option has a short \`.label\` (\u22645 words) and a full \`.description\`. Map \`next_steps.options[]\` into your host widget VERBATIM and in order: for \`AskUserQuestion\` (cowork / Claude Code) pass each as \`{label, description}\`; for \`ask_user_input_v0\` (Claude chat / ChatGPT, string options only) pass each option's \`.description\` as the string (it's the full sentence). Do NOT reword, reorder, drop, or prose-ify them \u2014 they're built deterministically by the server so the offer (incl. the artifact option at position 0) fires every time. Fall back to the table below only when there is NO \`next_steps\` field.
+
+**One exception \u2014 skip the widget** when the user's original message contained a complete sequential instruction chain ("show me X and then do Y") AND all stated steps have been completed. In that case, end with STOP directly \u2014 the user stated their full plan and does not need a "what next?" prompt.
+- Skip example: "Show me today's leads and then research the top one for me." \u2192 after research completes, emit STOP without the widget.
+- Do NOT skip for: plain requests ("show me today's leads", "run my check-in"), recurring-language requests ("I do this every day"), or requests where only one action was stated.
+
+Pick 2\u20134 rows from the (Observation, Suggest, Calls) table below most relevant to the response, then call your host's widget with ITS schema (per the schema rules above \u2014 wrong schema fails silently):
+- \`ask_user_input_v0\`: \`{questions:[{question,type:"single_select",options:["<Suggest 1>","<Suggest 2>"]}]}\`
+- \`AskUserQuestion\`: \`{questions:[{question,header:"Next step",multiSelect:false,options:[{label:"<\u22645 words>",description:"<Suggest 1>"}]}]}\`
+
+User picks \u2192 call the matching \`Calls\` tool. Constraints: 2\u20134 mutually-exclusive options, AskUserQuestion labels \u22645 words (full text in \`description\`), max 3 questions. Table stays internal; never recite it.
+
+---
+
+
+
+The overview itself returns no \`next_steps\` object, so when you DO propose, build the options from this table \u2014 pick the 2\u20134 rows that match what the account state actually showed. If none apply cleanly, propose none (the status read was complete) rather than inventing an option.
+
+All \`Calls\` below are agent-callable \`leadbay_*\` tools (never an MCP prompt name like \`leadbay_daily_check_in\` \u2014 the agent cannot invoke a prompt from a turn; route to the underlying tool instead).
+
+| Observation                                                         | Suggest                                                | Calls                                                        |
+|---------------------------------------------------------------------|--------------------------------------------------------|--------------------------------------------------------------|
+| Fresh discovery batch waiting / user wants new leads                | "See today's best new leads"                           | leadbay_pull_leads(lensId = pinned)                          |
+| Follow-ups due / known leads to re-engage                           | "Show follow-ups due now"                              | leadbay_pull_followups                                       |
+| Quota/credit read shows low or exhausted balance                    | "Review what's eating your quota"                      | leadbay_account_status (deeper read)                         |
+| Auth/connection blocker (e.g. 401 / AUTH_EXPIRED on a read)         | "Reconnect Leadbay to unblock actions"                 | (guide the user to re-authenticate \u2014 no tool call)           |
+| Lens audience looks mismatched (batch is off-ICP)                   | "Adjust the lens audience to match your ICP"           | ASK first \u2014 collect the target sectors / sizes / exclusions, THEN leadbay_adjust_audience(...) with those params. NEVER call it with no args (an empty call writes the current filter / may clone the default lens \u2014 a no-op or unwanted change). |
+| Status is healthy and nothing is pending                            | propose nothing \u2014 the overview is a complete answer    | \u2014                                                            |
+
 GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
 
 If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
@@ -11524,6 +11567,22 @@ function coerceCell(client, v, path) {
     return String(v);
   throw client.makeError("IMPORT_INVALID_CELL_TYPE", `Cell at ${path} is ${Array.isArray(v) ? "an array" : typeof v}, expected string|number|boolean|null`, `Convert the value to a string before passing.`, "POST /imports");
 }
+var LEAD_STATUSES = [
+  "DEFAULT",
+  "INBOUND",
+  "UNWANTED",
+  "WANTED",
+  "LOST",
+  "WON"
+];
+var LEAD_STATUS_SET = new Set(LEAD_STATUSES);
+function enforceLeadStatus(client, raw, path) {
+  const canonical = String(raw).trim().toUpperCase();
+  if (!LEAD_STATUS_SET.has(canonical)) {
+    throw client.makeError("IMPORT_INVALID_STATUS", `${path} ${JSON.stringify(raw)} is not a valid lead status`, `Use one of ${LEAD_STATUSES.join(", ")} (case-insensitive), or omit it.`, "POST /imports");
+  }
+  return canonical;
+}
 function prepareDomainsMode(client, inputs) {
   const validInputs = [];
   const malformedDomains = [];
@@ -11645,6 +11704,12 @@ function prepareRecordsMode(client, records, mappings, customFieldCatalog) {
     if (normDomain && !byDomain.has(normDomain))
       byDomain.set(normDomain, idx);
   });
+  const statuses = {};
+  for (const [cell, status] of Object.entries(mappings.statuses ?? {})) {
+    statuses[cell] = enforceLeadStatus(client, status, `mappings.statuses[${JSON.stringify(cell)}]`);
+  }
+  const rawDefault = mappings.default_status;
+  const default_status = rawDefault == null || String(rawDefault).trim() === "" ? null : enforceLeadStatus(client, rawDefault, "mappings.default_status");
   return {
     mode: "records",
     validInputs,
@@ -11654,8 +11719,8 @@ function prepareRecordsMode(client, records, mappings, customFieldCatalog) {
     header,
     mappings: {
       fields: { ...normalizedFields },
-      statuses: mappings.statuses ?? {},
-      default_status: mappings.default_status ?? null
+      statuses,
+      default_status
     }
   };
 }
@@ -12048,11 +12113,12 @@ var importLeads = {
           },
           statuses: {
             type: "object",
-            description: "Optional status string mapping (rarely needed). Defaults to {}."
+            description: `Optional map of raw CSV status-cell text \u2192 lead status (rarely needed). Keys are the verbatim cell strings; values must be one of ${LEAD_STATUSES.join(", ")} (case-insensitive). Defaults to {}.`
           },
           default_status: {
             type: ["string", "null"],
-            description: "Optional default status. Defaults to null."
+            enum: [...LEAD_STATUSES, null],
+            description: `Optional default lead status applied to rows without an explicit status. One of ${LEAD_STATUSES.join(", ")} (case-insensitive). Defaults to null.`
           }
         },
         required: ["fields"]
@@ -17627,8 +17693,15 @@ var importAndQualify = {
             type: "object",
             description: "Ergonomic shorthand: `{CsvColumn: <number-id>}` or `{CsvColumn: '<field-name>'}` for custom-field mappings. Resolved against /crm/custom_fields catalog."
           },
-          statuses: { type: "object", description: "Optional status string mapping." },
-          default_status: { type: ["string", "null"], description: "Optional default status." }
+          statuses: {
+            type: "object",
+            description: `Optional map of raw CSV status-cell text \u2192 lead status. Values must be one of ${LEAD_STATUSES.join(", ")} (case-insensitive); keys are the verbatim cell strings.`
+          },
+          default_status: {
+            type: ["string", "null"],
+            enum: [...LEAD_STATUSES, null],
+            description: `Optional default lead status. One of ${LEAD_STATUSES.join(", ")} (case-insensitive).`
+          }
         },
         // mappings has a closed shape (fields/custom_fields/statuses/default_status).
         // Inner objects (fields, custom_fields, statuses) keep open shapes
@@ -22095,6 +22168,56 @@ function buildServer(client, opts = {}) {
       };
     };
     try {
+      const bootstrapState = opts.bootstrapStatus?.() ?? { done: true };
+      if (!bootstrapState.done) {
+        const url = bootstrapState.signInUrl;
+        const envelope = bootstrapState.failureMessage ? {
+          error: true,
+          code: "AUTH_FAILED",
+          message: "Couldn't sign you in to Leadbay.",
+          hint: `Sign-in failed: ${bootstrapState.failureMessage}
+
+Restart the Leadbay extension in Claude Desktop to retry. If it keeps failing, check your network/region and that Leadbay is reachable.`
+        } : url ? {
+          // Prefer surfacing the live sign-in URL — the spawned MCP process
+          // often can't open a GUI browser itself (no DISPLAY / sanitized
+          // env), so a clickable link the agent renders is the reliable path.
+          error: true,
+          code: "AUTH_REQUIRED",
+          message: "Sign in to Leadbay to finish connecting.",
+          hint: `Open this link to authorize Leadbay, then re-run this tool:
+
+${url}
+
+` + (bootstrapState.openFailed ? "(The extension couldn't open your browser automatically.)" : "(A browser may have opened automatically \u2014 if not, use the link above.)")
+        } : {
+          error: true,
+          code: "AUTH_PENDING",
+          message: "Signing you in to Leadbay \u2014 a browser window should have opened. Authorize there, then try again.",
+          hint: "Complete the Leadbay sign-in in your browser, then re-run this tool."
+        };
+        const pendingText = formatErrorForLLM(envelope);
+        const pendingDur = Date.now() - callStart;
+        telemetry.captureToolCall({
+          tool: name,
+          ok: false,
+          duration_ms: pendingDur,
+          format: "error-envelope",
+          bytes: pendingText.length,
+          error_code: envelope.code,
+          triggered_by
+        });
+        if (DEBUG_ON) {
+          process.stderr.write(
+            `[leadbay-mcp debug] tool=${name} dur=${pendingDur}ms ok=false code=${envelope.code} (auth-bootstrap, no-sentry)
+`
+          );
+        }
+        return {
+          content: [{ type: "text", text: pendingText }],
+          isError: true
+        };
+      }
       if (COMPOSITE_FILE_TOOL_NAMES.has(name) && !triggered_by) {
         const envelope = {
           error: true,
@@ -22461,7 +22584,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.21.0" : "0.0.0-dev";
+var VERSION = true ? "0.21.2" : "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();