@leadbay/mcp 0.15.1 → 0.16.2

package/dist/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  COMPOSITE_FILE_TOOL_NAMES,
   LeadbayClient,
   agentMemoryTools,
   compositeReadTools,
@@ -11,7 +12,7 @@ import {
   granularWriteTools,
   resolveAgentMemorySummary,
   resolveRegion
-} from "./chunk-5IL7SC7L.js";
+} from "./chunk-3V3EPBLZ.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -568,7 +569,9 @@ If the prompt's body and the tool's RENDERING appear to conflict, the tool's REN
 
 
 # PHASE 1 \u2014 LAUNCH
-Call \`leadbay_bulk_qualify_leads\` with \`count={{arg:count_or_default}}\`.
+Call \`leadbay_bulk_qualify_leads\` with \`count={{arg:count_or_default}}\` and \`wait_for_completion=true\` (synchronous mode \u2014 waits for results before returning).
+
+**Resilience rule:** If \`leadbay_bulk_qualify_leads\` returns a BulkTracker-not-configured error or similar infrastructure error, do NOT retry with \`wait_for_completion=false\`. Instead, proceed directly to Phase 3 and call \`leadbay_pull_leads\` to surface the already-qualified leads in the current batch.
 
 # PHASE 2 \u2014 POLL
 While it polls, expect notifications / progress events showing per-lead transitions. Surface meaningful ones (e.g. "lead X just finished") to me as they arrive \u2014 one inline status sentence per check, never expanded into a card:
@@ -591,9 +594,13 @@ After the status line, propose the obvious refresh / progress-check / recovery a
 
 When \`bulk_qualify_leads\` returns, surface results in two parts.
 
-**Status line first** \u2014 one sentence using the status-inline shape above: how many qualified, how many are still running (name them by lead_id + lead name if available so the user can poll later).
+**Status line first** \u2014 one sentence in this exact format: "\u2713 N leads qualified \xB7 M still processing (lead IDs: X, Y, Z)". Variants:
+- If bulk_qualify returns \`exhausted=true\` or \`total_unqualified_found=0\` (all leads were already qualified): "\u2713 All N/N leads already qualified \xB7 0 still processing" \u2014 use the actual count (e.g. "All 10/10 leads already qualified")
+- If all newly qualified (none still pending): "\u2713 N leads qualified"
+- If some still pending: "\u2713 N leads qualified \xB7 M still processing (lead IDs: X, Y, Z)"
+- If all still processing: "\u2713 0 leads qualified \xB7 N still processing (lead IDs: X, Y, Z)"
 
-**Then a refreshed table** \u2014 re-pull the newly-qualified leads via \`leadbay_pull_leads\` with the same \`lensId\` and render them using the canonical pull_leads layout:
+**Then a refreshed table** \u2014 call \`leadbay_pull_leads\` to fetch the current batch (this is always required \u2014 the qualification results do not include the full lead data needed to render the table). Use the same \`lensId\` and render using the canonical pull_leads layout:
 
 ## RENDERING \u2014 markdown table, three columns, score-bar driven
 
@@ -1353,6 +1360,7 @@ var EV_AGENT_MEMORY_CAPTURED = "agent_memory_captured";
 var EV_AGENT_MEMORY_RECALLED = "agent_memory_recalled";
 var EV_AGENT_MEMORY_PRUNED = "agent_memory_pruned";
 var EV_FRICTION_REPORTED = "mcp friction reported";
+var EV_COMPOSITE_CALL = "mcp composite call";
 
 // src/telemetry.ts
 var NOOP_TELEMETRY = {
@@ -1360,6 +1368,8 @@ var NOOP_TELEMETRY = {
   },
   captureToolCall: () => {
   },
+  captureCompositeCall: () => {
+  },
   captureQuotaHit: () => {
   },
   captureTopupLink: () => {
@@ -1558,6 +1568,9 @@ function initTelemetry(opts) {
     captureToolCall(props) {
       emit(EV_TOOL_CALL, { ...props });
     },
+    captureCompositeCall(props) {
+      emit(EV_COMPOSITE_CALL, { ...props });
+    },
     captureQuotaHit(props) {
       emit(EV_QUOTA_HIT, { ...props });
     },
@@ -2099,27 +2112,27 @@ function formatErrorForLLM(err) {
   return String(err);
 }
 var TRIGGERED_BY_FIELD = "_triggered_by";
-var TRIGGERED_BY_DESCRIPTION = "OPTIONAL METADATA \u2014 the verbatim user utterance (or short paraphrase) that led you to call this tool. Pass the user's literal phrasing (last 1-3 sentences). Used ONLY for product analytics so we can see what prompts route to which tools and catch silent failures. Does not affect tool behavior. Always include when you have it.";
-function withTriggeredByMeta(tool) {
+var TRIGGERED_BY_DESCRIPTION_OPTIONAL = "OPTIONAL METADATA \u2014 the verbatim user utterance (or short paraphrase) that led you to call this tool. Pass the user's literal phrasing (last 1-3 sentences). Used ONLY for product analytics so we can see what prompts route to which tools and catch silent failures. Does not affect tool behavior. Always include when you have it.";
+var TRIGGERED_BY_DESCRIPTION_MANDATORY = `MANDATORY \u2014 copy/paste the verbatim portion of the user's most recent message that this call is acting upon. Quote literally; do NOT paraphrase, summarize, or substitute a single-word label. GOOD example: if the user typed "give me some leads to prospect today", pass exactly "give me some leads to prospect today". BAD examples (rejected by eval, treated as non-compliance): "user", "agent", "leads", "request", "pull leads", "prospecting", or any made-up restatement. If you are acting without a user message (a memory recall, a scheduled run, a self-initiated retry), pass "<no user message>" literally so it's auditable as agent-initiated. Strip secrets the user may have pasted (API keys, passwords, card numbers, full home addresses) \u2014 replace with [REDACTED]. The call is rejected as LAST_PROMPT_REQUIRED if missing or blank.`;
+function withTriggeredByMeta(tool, opts = { mandatory: false }) {
   const schema = tool.inputSchema;
   if (!schema || schema.type !== "object") return tool;
   const existingProps = schema.properties ?? {};
   if (Object.prototype.hasOwnProperty.call(existingProps, TRIGGERED_BY_FIELD)) {
     return tool;
   }
-  return {
-    ...tool,
-    inputSchema: {
-      ...schema,
-      properties: {
-        ...existingProps,
-        [TRIGGERED_BY_FIELD]: {
-          type: "string",
-          description: TRIGGERED_BY_DESCRIPTION
-        }
-      }
+  const description = opts.mandatory ? TRIGGERED_BY_DESCRIPTION_MANDATORY : TRIGGERED_BY_DESCRIPTION_OPTIONAL;
+  const existingRequired = Array.isArray(schema.required) ? schema.required : [];
+  const nextRequired = opts.mandatory ? [...existingRequired, TRIGGERED_BY_FIELD] : existingRequired;
+  const nextSchema = {
+    ...schema,
+    properties: {
+      ...existingProps,
+      [TRIGGERED_BY_FIELD]: { type: "string", description }
     }
   };
+  if (nextRequired.length > 0) nextSchema.required = nextRequired;
+  return { ...tool, inputSchema: nextSchema };
 }
 function extractTriggeredBy(args) {
   const raw = args[TRIGGERED_BY_FIELD];
@@ -2172,7 +2185,12 @@ function buildServer(client, opts = {}) {
   const toolByName = /* @__PURE__ */ new Map();
   for (const t of exposedTools) {
     if (!toolByName.has(t.name) && t.name !== "leadbay_login") {
-      toolByName.set(t.name, withTriggeredByMeta(t));
+      toolByName.set(
+        t.name,
+        withTriggeredByMeta(t, {
+          mandatory: COMPOSITE_FILE_TOOL_NAMES.has(t.name)
+        })
+      );
     }
   }
   const exposedNames = new Set(toolByName.keys());
@@ -2397,6 +2415,14 @@ function buildServer(client, opts = {}) {
       };
     };
     try {
+      if (COMPOSITE_FILE_TOOL_NAMES.has(name) && !triggered_by) {
+        throw {
+          error: true,
+          code: "LAST_PROMPT_REQUIRED",
+          message: "Every call to this composite tool must carry `_triggered_by` \u2014 the verbatim part of the user's most recent message this call is acting upon (secrets stripped).",
+          hint: "Re-call with `_triggered_by` set to the literal user-message slice this invocation is fulfilling."
+        };
+      }
       const result = await tool.execute(client, args, {
         logger: opts.logger,
         bulkTracker: opts.bulkTracker,
@@ -2425,6 +2451,15 @@ function buildServer(client, opts = {}) {
           error_code: envCode,
           triggered_by
         });
+        if (COMPOSITE_FILE_TOOL_NAMES.has(name)) {
+          telemetry.captureCompositeCall({
+            tool: name,
+            last_prompt: triggered_by ?? "",
+            ok: false,
+            duration_ms: envDur,
+            error_code: envCode
+          });
+        }
         telemetry.captureException(
           result,
           buildBusinessCtx(name, result, triggered_by)
@@ -2461,6 +2496,14 @@ function buildServer(client, opts = {}) {
           bytes: mdBytes,
           triggered_by
         });
+        if (COMPOSITE_FILE_TOOL_NAMES.has(name)) {
+          telemetry.captureCompositeCall({
+            tool: name,
+            last_prompt: triggered_by ?? "",
+            ok: true,
+            duration_ms: mdDur
+          });
+        }
         captureAgentMemoryTelemetry(name, env.structured);
         captureFrictionTelemetry(name, env.structured);
         if (name === "leadbay_create_topup_link" && typeof env.structured?.url === "string") {
@@ -2493,6 +2536,14 @@ function buildServer(client, opts = {}) {
         bytes: okBytes,
         triggered_by
       });
+      if (COMPOSITE_FILE_TOOL_NAMES.has(name)) {
+        telemetry.captureCompositeCall({
+          tool: name,
+          last_prompt: triggered_by ?? "",
+          ok: true,
+          duration_ms: okDur
+        });
+      }
       captureAgentMemoryTelemetry(name, result);
       captureFrictionTelemetry(name, result);
       if (name === "leadbay_create_topup_link" && typeof result?.url === "string") {
@@ -2526,6 +2577,15 @@ function buildServer(client, opts = {}) {
           error_code: code,
           triggered_by
         });
+        if (COMPOSITE_FILE_TOOL_NAMES.has(name)) {
+          telemetry.captureCompositeCall({
+            tool: name,
+            last_prompt: triggered_by ?? "",
+            ok: false,
+            duration_ms: errDur,
+            error_code: code
+          });
+        }
         telemetry.captureException(err, buildBusinessCtx(name, err, triggered_by));
       } else {
         telemetry.captureException(err, {
@@ -2543,6 +2603,15 @@ function buildServer(client, opts = {}) {
           error_code: code,
           triggered_by
         });
+        if (COMPOSITE_FILE_TOOL_NAMES.has(name)) {
+          telemetry.captureCompositeCall({
+            tool: name,
+            last_prompt: triggered_by ?? "",
+            ok: false,
+            duration_ms: errDur,
+            error_code: code
+          });
+        }
       }
       if (DEBUG_ON) {
         process.stderr.write(
@@ -2754,9 +2823,373 @@ async function createDefaultUpdateStateStore(opts = {}) {
   }
 }
 
+// src/oauth.ts
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { request as httpsRequestRaw } from "https";
+import { spawn } from "child_process";
+var STARGATE_URLS = {
+  prod: "https://stargate.leadbay.app/1.0/user_info",
+  staging: "https://staging.stargate.leadbay.app/1.0/user_info"
+};
+var FR_COUNTRY_CODES = /* @__PURE__ */ new Set([
+  "FR",
+  // France
+  // French overseas territories — same regional partition as France in the
+  // backend's stargate /login route (see backend/specs/stargate/1.0).
+  "GP",
+  "MQ",
+  "GF",
+  "RE",
+  "YT",
+  "MF",
+  "BL",
+  "PM",
+  "WF",
+  "PF",
+  "NC",
+  "TF"
+]);
+async function inferRegionViaStargate(opts) {
+  const url = STARGATE_URLS[opts.staging ? "staging" : "prod"];
+  const res = await httpsCall("GET", url, { Accept: "application/json" });
+  if (res.status !== 200) {
+    throw new Error(
+      `Stargate region probe failed: GET ${url} returned ${res.status}. Pass --region us|fr to skip auto-detection.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    throw new Error(`Stargate region probe returned non-JSON body`);
+  }
+  const country = parsed.userCountry;
+  if (!country || typeof country !== "string") {
+    throw new Error(`Stargate response missing userCountry: ${res.body.slice(0, 200)}`);
+  }
+  if (country === "US") return "us";
+  if (FR_COUNTRY_CODES.has(country)) return "fr";
+  throw new Error(
+    `Stargate detected your country as ${country}, which isn't mapped to a Leadbay region. Pass --region us|fr explicitly.`
+  );
+}
+function generatePkce() {
+  const verifier = base64UrlEncode(randomBytes(32));
+  const challenge = base64UrlEncode(
+    createHash("sha256").update(verifier, "ascii").digest()
+  );
+  return { verifier, challenge, method: "S256" };
+}
+function base64UrlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function httpsCall(method, url, headers, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const reqHeaders = { ...headers };
+    if (body !== void 0) reqHeaders["Content-Length"] = Buffer.byteLength(body);
+    const req = httpsRequestRaw(
+      {
+        hostname: u.hostname,
+        port: u.port ? Number(u.port) : 443,
+        path: u.pathname + u.search,
+        method,
+        headers: reqHeaders
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on(
+          "end",
+          () => resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf8") })
+        );
+      }
+    );
+    req.on("error", reject);
+    if (body !== void 0) req.write(body);
+    req.end();
+  });
+}
+async function fetchDiscoveryDoc(authServerBaseUrl) {
+  const url = trimSlash(authServerBaseUrl) + "/.well-known/oauth-authorization-server";
+  const res = await httpsCall("GET", url, { Accept: "application/json" });
+  if (res.status !== 200) {
+    throw new Error(
+      `OAuth discovery failed: GET ${url} returned ${res.status}. Either OAuth isn't deployed to this backend yet, or the URL is wrong.`
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(res.body);
+  } catch {
+    throw new Error(`OAuth discovery returned non-JSON body from ${url}`);
+  }
+  for (const field of ["authorization_endpoint", "token_endpoint", "registration_endpoint"]) {
+    if (typeof doc[field] !== "string" || !doc[field]) {
+      throw new Error(`OAuth discovery doc missing required field: ${field}`);
+    }
+  }
+  if (doc.code_challenge_methods_supported && !doc.code_challenge_methods_supported.includes("S256")) {
+    throw new Error(
+      `OAuth server doesn't support S256 PKCE (only ${doc.code_challenge_methods_supported.join(", ")}). Aborting \u2014 plain PKCE is too weak for a public client.`
+    );
+  }
+  return doc;
+}
+function trimSlash(s) {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+async function registerClient(registrationEndpoint, params) {
+  const body = JSON.stringify({
+    client_name: params.clientName,
+    redirect_uris: [params.redirectUri],
+    logo_uri: params.logoUri,
+    token_endpoint_auth_method: "none"
+    // public client
+  });
+  const res = await httpsCall(
+    "POST",
+    registrationEndpoint,
+    { "Content-Type": "application/json", Accept: "application/json" },
+    body
+  );
+  if (res.status === 429) {
+    throw new Error(
+      `OAuth client registration rate-limited (429). The backend allows ~10 registrations per IP per hour. Wait and retry, or use the password flow (drop the --oauth flag).`
+    );
+  }
+  if (res.status !== 201 && res.status !== 200) {
+    throw new Error(
+      `OAuth client registration failed: POST ${registrationEndpoint} \u2192 ${res.status} ${res.body.slice(0, 300)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    throw new Error(`OAuth client registration returned non-JSON body`);
+  }
+  if (!parsed.client_id) {
+    throw new Error(`OAuth client registration response missing client_id`);
+  }
+  return parsed;
+}
+async function startLoopbackListener(opts) {
+  let resolveCallback;
+  let rejectCallback;
+  const callbackPromise = new Promise((res, rej) => {
+    resolveCallback = res;
+    rejectCallback = rej;
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (req.method !== "GET" || url.pathname !== "/callback") {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    const params = url.searchParams;
+    const errParam = params.get("error");
+    if (errParam) {
+      const desc = params.get("error_description") ?? "";
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(renderHtml("Authorization failed", `${errParam}${desc ? `: ${desc}` : ""}`));
+      rejectCallback(new Error(`OAuth authorization denied: ${errParam}${desc ? ` (${desc})` : ""}`));
+      return;
+    }
+    const code = params.get("code");
+    const state = params.get("state");
+    if (!code || !state) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(renderHtml("Authorization failed", "Missing code or state parameter."));
+      rejectCallback(new Error("OAuth callback missing code or state"));
+      return;
+    }
+    if (state !== opts.expectedState) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(renderHtml("Authorization failed", "Invalid state parameter (possible CSRF)."));
+      rejectCallback(new Error("OAuth callback state mismatch (possible CSRF)"));
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(renderHtml("You're signed in", "You can close this tab and return to the terminal."));
+    resolveCallback({ code, state });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const addr = server.address();
+  const redirectUri = `http://127.0.0.1:${addr.port}/callback`;
+  const timer = setTimeout(() => {
+    rejectCallback(new Error(`OAuth login timed out after ${Math.round(opts.timeoutMs / 1e3)}s`));
+  }, opts.timeoutMs);
+  return {
+    redirectUri,
+    waitForCallback: () => callbackPromise.finally(() => {
+      clearTimeout(timer);
+    }),
+    close: () => {
+      clearTimeout(timer);
+      server.close();
+    }
+  };
+}
+function renderHtml(title, message) {
+  const safeTitle = escapeHtml(title);
+  const safeMsg = escapeHtml(message);
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8"><title>${safeTitle} \u2014 Leadbay MCP</title>
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+     display:flex;align-items:center;justify-content:center;height:100vh;
+     margin:0;background:#fafafa;color:#111}
+.card{padding:32px 40px;border:1px solid #eee;border-radius:12px;
+      background:#fff;max-width:420px;text-align:center}
+h1{font-size:18px;margin:0 0 12px;font-weight:600}
+p{margin:0;color:#555;font-size:14px;line-height:1.5}
+</style></head>
+<body><div class="card"><h1>${safeTitle}</h1><p>${safeMsg}</p></div></body></html>`;
+}
+function escapeHtml(s) {
+  return s.replace(
+    /[&<>"']/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]
+  );
+}
+async function exchangeCodeForToken(opts) {
+  const form = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: opts.code,
+    redirect_uri: opts.redirectUri,
+    client_id: opts.clientId,
+    code_verifier: opts.codeVerifier
+  }).toString();
+  const res = await httpsCall(
+    "POST",
+    opts.tokenEndpoint,
+    {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    form
+  );
+  if (res.status !== 200) {
+    throw new Error(
+      `OAuth token exchange failed: POST ${opts.tokenEndpoint} \u2192 ${res.status} ${res.body.slice(0, 300)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    throw new Error("OAuth token endpoint returned non-JSON body");
+  }
+  if (!parsed.access_token) {
+    throw new Error(`OAuth token response missing access_token: ${res.body.slice(0, 200)}`);
+  }
+  return { accessToken: parsed.access_token };
+}
+async function openInBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+  let args;
+  if (platform === "darwin") {
+    cmd = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    cmd = "cmd";
+    args = ["/c", "start", '""', url];
+  } else {
+    cmd = "xdg-open";
+    args = [url];
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", reject);
+    child.on("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+async function oauthLogin(opts) {
+  const log = opts.log ?? (() => {
+  });
+  const open = opts.openBrowser ?? openInBrowser;
+  const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1e3;
+  log(`Discovering OAuth endpoints at ${opts.authServerBaseUrl}\u2026
+`);
+  const doc = await fetchDiscoveryDoc(opts.authServerBaseUrl);
+  const state = base64UrlEncode(randomBytes(16));
+  const pkce = generatePkce();
+  log("Starting loopback listener on 127.0.0.1\u2026\n");
+  const listener = await startLoopbackListener({ expectedState: state, timeoutMs });
+  try {
+    log(`Registering client at ${doc.registration_endpoint}\u2026
+`);
+    const client = await registerClient(doc.registration_endpoint, {
+      clientName: opts.clientName,
+      redirectUri: listener.redirectUri,
+      logoUri: opts.logoUri
+    });
+    const authorizeUrl = new URL(doc.authorization_endpoint);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", client.client_id);
+    authorizeUrl.searchParams.set("redirect_uri", listener.redirectUri);
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("code_challenge", pkce.challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", pkce.method);
+    log(`Opening browser to authorize\u2026
+  ${authorizeUrl.toString()}
+`);
+    try {
+      await open(authorizeUrl.toString());
+    } catch (err) {
+      log(
+        `Could not open browser automatically (${err?.message ?? err}). Open this URL manually:
+  ${authorizeUrl.toString()}
+`
+      );
+    }
+    log("Waiting for authorization (5 min timeout)\u2026\n");
+    const { code } = await listener.waitForCallback();
+    log("Exchanging authorization code for access token\u2026\n");
+    const { accessToken } = await exchangeCodeForToken({
+      tokenEndpoint: doc.token_endpoint,
+      code,
+      codeVerifier: pkce.verifier,
+      clientId: client.client_id,
+      redirectUri: listener.redirectUri
+    });
+    return { accessToken };
+  } finally {
+    listener.close();
+  }
+}
+
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.15.1";
+var OAUTH_BASE_URLS = {
+  prod: {
+    us: "https://api-us.leadbay.app",
+    fr: "https://api-fr.leadbay.app"
+  },
+  staging: {
+    us: "https://api-us-staging.leadbay.app",
+    fr: "https://staging.api.leadbay.app"
+  }
+};
+var VERSION = "0.16.2";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -2805,7 +3238,7 @@ EXAMPLE Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
     "mcpServers": {
       "leadbay": {
         "command": "npx",
-        "args": ["-y", "@leadbay/mcp@0.13"],
+        "args": ["-y", "@leadbay/mcp@0.16"],
         "env": {
           "LEADBAY_TOKEN": "lb_...",
           "LEADBAY_REGION": "us",
@@ -2878,9 +3311,151 @@ function makeBrokenClient(stubError, region) {
   const baseUrl = region === "fr" ? "https://api-fr.leadbay.app" : "https://api-us.leadbay.app";
   return new BrokenLeadbayClient(stubError, baseUrl, region);
 }
+function hydrateEnvFromCredentialsFile() {
+  if (process.env.LEADBAY_TOKEN) return false;
+  try {
+    const { existsSync, readFileSync } = require_("node:fs");
+    const { path } = resolveOAuthBootstrapCredentialsPath();
+    if (!existsSync(path)) return false;
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const env = parsed?.mcpServers?.leadbay?.env;
+    if (!env || typeof env !== "object") return false;
+    if (typeof env.LEADBAY_TOKEN === "string" && env.LEADBAY_TOKEN.length > 0) {
+      process.env.LEADBAY_TOKEN = env.LEADBAY_TOKEN;
+    }
+    if (!process.env.LEADBAY_REGION && typeof env.LEADBAY_REGION === "string") {
+      process.env.LEADBAY_REGION = env.LEADBAY_REGION;
+    }
+    if (!process.env.LEADBAY_BASE_URL && typeof env.LEADBAY_BASE_URL === "string") {
+      process.env.LEADBAY_BASE_URL = env.LEADBAY_BASE_URL;
+    }
+    return !!process.env.LEADBAY_TOKEN;
+  } catch {
+    return false;
+  }
+}
+function resolveOAuthBootstrapCredentialsPath() {
+  const resolved = resolveDefaultCredentialsPath();
+  if (process.env.LEADBAY_OAUTH_STAGING !== "1") return resolved;
+  const { dirname: dirname2, join } = require_("node:path");
+  return {
+    path: join(dirname2(resolved.path), "credentials.staging.json"),
+    legacy: resolved.legacy
+  };
+}
+async function bootstrapOAuthIfMissing(logger) {
+  if (process.env.LEADBAY_TOKEN) return false;
+  const { hostname } = await import("os");
+  process.stderr.write(
+    `
+[leadbay-mcp@${VERSION}] No token found \u2014 starting OAuth login in your browser\u2026
+  (This is a one-time setup. The resulting token will be persisted at
+   ${(() => {
+      try {
+        return resolveOAuthBootstrapCredentialsPath().path;
+      } catch {
+        return "<credentials file>";
+      }
+    })()}
+   so subsequent launches start instantly.)
+
+`
+  );
+  const envBaseUrl = process.env.LEADBAY_BASE_URL;
+  const envRegion = process.env.LEADBAY_REGION;
+  const isStaging = process.env.LEADBAY_OAUTH_STAGING === "1" || !!envBaseUrl && /staging/.test(envBaseUrl);
+  let region;
+  let authServerBaseUrl;
+  try {
+    if (envBaseUrl) {
+      authServerBaseUrl = envBaseUrl;
+      region = /(-fr|staging\.api)/.test(envBaseUrl) ? "fr" : "us";
+    } else if (envRegion === "us" || envRegion === "fr") {
+      region = envRegion;
+      authServerBaseUrl = OAUTH_BASE_URLS[isStaging ? "staging" : "prod"][region];
+    } else {
+      region = await inferRegionViaStargate({ staging: isStaging });
+      authServerBaseUrl = OAUTH_BASE_URLS[isStaging ? "staging" : "prod"][region];
+    }
+    const { accessToken } = await oauthLogin({
+      authServerBaseUrl,
+      clientName: `Leadbay MCP @ ${hostname()}`,
+      log: (m) => process.stderr.write(m)
+    });
+    try {
+      const { writeFileSync, mkdirSync, chmodSync } = require_("node:fs");
+      const { dirname: dirname2 } = require_("node:path");
+      const { path } = resolveOAuthBootstrapCredentialsPath();
+      const envBlock = {
+        LEADBAY_TOKEN: accessToken,
+        LEADBAY_REGION: region
+      };
+      if (isStaging || envBaseUrl) envBlock.LEADBAY_BASE_URL = authServerBaseUrl;
+      const config = {
+        mcpServers: {
+          leadbay: {
+            command: "npx",
+            args: ["-y", `@leadbay/mcp@${VERSION.split(".").slice(0, 2).join(".")}`],
+            env: envBlock
+          }
+        }
+      };
+      mkdirSync(dirname2(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+      try {
+        chmodSync(path, 384);
+      } catch {
+      }
+      process.stderr.write(`[leadbay-mcp] Persisted credentials to ${path}
+`);
+    } catch (err) {
+      process.stderr.write(
+        `[leadbay-mcp warn] OAuth succeeded but persisting the token failed (${err?.message ?? err}). You'll be prompted to re-authorize on next launch.
+`
+      );
+    }
+    process.env.LEADBAY_TOKEN = accessToken;
+    process.env.LEADBAY_REGION = region;
+    if (isStaging || envBaseUrl) process.env.LEADBAY_BASE_URL = authServerBaseUrl;
+    logger.info?.(`OAuth bootstrap complete \u2014 region=${region}`);
+    return true;
+  } catch (err) {
+    process.stderr.write(
+      `[leadbay-mcp] OAuth bootstrap failed: ${err?.message ?? err}
+  The server will start but tools will return AUTH_MISSING until you authorize.
+`
+    );
+    return false;
+  }
+}
 async function resolveClientFromEnv(logger) {
+  if (process.env.LEADBAY_OAUTH_BOOTSTRAP === "1") {
+    hydrateEnvFromCredentialsFile();
+    if (!process.env.LEADBAY_TOKEN) {
+      await bootstrapOAuthIfMissing(logger);
+    }
+  }
   const token = process.env.LEADBAY_TOKEN;
   if (!token) {
+    if (process.env.LEADBAY_OAUTH_BOOTSTRAP === "1") {
+      process.stderr.write(
+        "leadbay-mcp: OAuth authorization is required but no token is available.\n  Restart the Claude Desktop extension to authorize Leadbay in your browser.\n\nRun `leadbay-mcp --help` for the full config template.\n"
+      );
+      const regionEnv3 = process.env.LEADBAY_REGION;
+      const region2 = regionEnv3 === "fr" ? "fr" : "us";
+      return {
+        client: makeBrokenClient(
+          {
+            error: true,
+            code: "AUTH_MISSING",
+            message: "Leadbay OAuth authorization has not completed.",
+            hint: "Restart the Claude Desktop extension and complete the Leadbay OAuth browser authorization."
+          },
+          region2
+        ),
+        authState: "missing"
+      };
+    }
     process.stderr.write(
       "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Run: npx -y @leadbay/mcp install --email <you> --region <us|fr>\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
     );
@@ -3027,7 +3602,7 @@ function checkLoginCollision(existingConfig, email, region) {
   const cfg = existingConfig;
   const existingEmail = typeof cfg.email === "string" && cfg.email.length > 0 ? cfg.email : void 0;
   const existingRegion = typeof cfg.mcpServers?.leadbay?.env?.LEADBAY_REGION === "string" ? cfg.mcpServers.leadbay.env.LEADBAY_REGION : void 0;
-  if (existingEmail !== void 0 && existingEmail !== email) {
+  if (existingEmail !== void 0 && email !== void 0 && existingEmail !== email) {
     return `existing email=${existingEmail} (this login is email=${email})`;
   }
   if (existingRegion !== void 0 && existingRegion !== region) {
@@ -3053,6 +3628,8 @@ function computeFreshDefaultPath() {
   return path.join(home, ".config", "leadbay", "credentials.json");
 }
 async function runLogin(args) {
+  const useOAuth = hasFlag(args, "oauth");
+  const useStaging = hasFlag(args, "staging");
   const email = parseFlag(args, "email");
   const defaultPathPreview = (() => {
     try {
@@ -3061,11 +3638,15 @@ async function runLogin(args) {
       return "<HOME>/.config/leadbay/credentials.json";
     }
   })();
-  if (!email) {
+  if (!email && !useOAuth) {
     process.stderr.write(
       `Usage: leadbay-mcp login --email you@example.com [--region us|fr] [--allow-region-fallback]
                         [--write-config PATH] [--unsafe-print-token] [--force] [--quiet]
+       leadbay-mcp login --oauth [--region us|fr] [--staging] [--write-config PATH] [--force] [--quiet]
   Then enter your password (hidden), or pipe it via stdin / set $LEADBAY_PASSWORD.
+  --oauth             Use OAuth Authorization Code + PKCE in your browser instead of email/password.
+                      Region is auto-detected via stargate GeoIP; pass --region to override.
+  --staging           Point at staging.leadbay.app endpoints. Use with --oauth for testing.
   --region            Pin the backend (us|fr); avoids sending your password to a backend you don't use.
                       Defaults to $LEADBAY_REGION if set; otherwise asks you to pass --allow-region-fallback.
   --allow-region-fallback   Try us, then fr (or fr, then us). Your password hits BOTH backends if the
@@ -3092,45 +3673,82 @@ async function runLogin(args) {
 `);
     return 2;
   }
-  if (!pinnedRegion && !allowFallback) {
+  if (!pinnedRegion && !allowFallback && !useOAuth) {
     process.stderr.write(
       "leadbay-mcp login: refusing to auto-detect region without consent.\n  Avoiding silent credential cross-leak: by default, --region (or $LEADBAY_REGION) must be set\n  so your password only ever hits the backend that owns your account.\n  Either:\n    --region us    (or --region fr)\n  or, if you don't know your region and accept the trade-off:\n    --allow-region-fallback   (your password will hit BOTH backends if the first 401s)\n"
     );
     return 2;
   }
-  const password = await readPassword();
-  if (!password) {
-    process.stderr.write("leadbay-mcp login: empty password\n");
-    return 2;
-  }
   let result;
-  try {
-    if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-2NAFYPXG.js");
-      const baseUrl = REGIONS[pinnedRegion];
-      const c = createClient({ region: pinnedRegion });
-      const token = await loginAt(baseUrl, email, password);
-      result = { region: pinnedRegion, baseUrl, token, verified: true };
-      void c;
+  if (useOAuth) {
+    let region;
+    if (pinnedRegion) {
+      region = pinnedRegion;
     } else {
-      result = await resolveRegion(email, password, pinnedRegion ?? void 0);
+      try {
+        process.stderr.write("Detecting your region from stargate\u2026\n");
+        region = await inferRegionViaStargate({ staging: useStaging });
+        process.stderr.write(`Detected region: ${region.toUpperCase()}
+`);
+      } catch (err) {
+        process.stderr.write(`leadbay-mcp@${VERSION} login --oauth: ${err?.message ?? String(err)}
+`);
+        await reportCliFailure("__oauth_login__", err);
+        return 1;
+      }
     }
-  } catch (err) {
-    process.stderr.write(`leadbay-mcp@${VERSION} login: ${err?.message ?? String(err)}
+    const baseUrl = OAUTH_BASE_URLS[useStaging ? "staging" : "prod"][region];
+    try {
+      const { hostname } = await import("os");
+      const clientName = `Leadbay MCP @ ${hostname()}`;
+      const { accessToken } = await oauthLogin({
+        authServerBaseUrl: baseUrl,
+        clientName,
+        log: (m) => process.stderr.write(m)
+      });
+      result = { region, baseUrl, token: accessToken, verified: true };
+    } catch (err) {
+      process.stderr.write(`leadbay-mcp@${VERSION} login --oauth: ${err?.message ?? String(err)}
 `);
-    await reportCliFailure("__login__", err);
-    return 1;
+      await reportCliFailure("__oauth_login__", err);
+      return 1;
+    }
+  } else {
+    const password = await readPassword();
+    if (!password) {
+      process.stderr.write("leadbay-mcp login: empty password\n");
+      return 2;
+    }
+    try {
+      if (pinnedRegion && !allowFallback) {
+        const { REGIONS } = await import("./dist-7XHTMWB2.js");
+        const baseUrl = REGIONS[pinnedRegion];
+        const c = createClient({ region: pinnedRegion });
+        const token = await loginAt(baseUrl, email, password);
+        result = { region: pinnedRegion, baseUrl, token, verified: true };
+        void c;
+      } else {
+        result = await resolveRegion(email, password, pinnedRegion ?? void 0);
+      }
+    } catch (err) {
+      process.stderr.write(`leadbay-mcp@${VERSION} login: ${err?.message ?? String(err)}
+`);
+      await reportCliFailure("__login__", err);
+      return 1;
+    }
   }
+  const envBlock = {
+    LEADBAY_TOKEN: result.token,
+    LEADBAY_REGION: result.region
+  };
+  if (useStaging) envBlock.LEADBAY_BASE_URL = result.baseUrl;
   const config = {
-    email,
+    ...email ? { email } : {},
     mcpServers: {
       leadbay: {
         command: "npx",
-        args: ["-y", "@leadbay/mcp@0.13"],
-        env: {
-          LEADBAY_TOKEN: result.token,
-          LEADBAY_REGION: result.region
-        }
+        args: ["-y", "@leadbay/mcp@0.16"],
+        env: envBlock
       }
     }
   };
@@ -3166,7 +3784,7 @@ Or for Claude Code (token included \u2014 same warning applies):
   claude mcp add leadbay --scope user \\
     --env LEADBAY_TOKEN=${result.token} \\
     --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.13
+    -- npx -y @leadbay/mcp@0.16
 
 Restart your MCP client to pick up the new server.
 `
@@ -3272,7 +3890,7 @@ For Claude Code, run:
   claude mcp add leadbay --scope user \\
     --env LEADBAY_TOKEN=$(jq -r .mcpServers.leadbay.env.LEADBAY_TOKEN ${quotedPath}) \\
     --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.13
+    -- npx -y @leadbay/mcp@0.16
 `
     );
   }
@@ -3452,7 +4070,7 @@ function buildClaudeCodeAddArgs(token, region, includeWrite, telemetryEnabled) {
     `LEADBAY_TELEMETRY_ENABLED=${telemetryEnabled ? "true" : "false"}`
   ];
   if (!includeWrite) args.push("--env", `LEADBAY_MCP_WRITE=0`);
-  args.push("--", "npx", "-y", "@leadbay/mcp@0.13");
+  args.push("--", "npx", "-y", "@leadbay/mcp@0.16");
   return args;
 }
 async function installInClaudeCode(token, region, includeWrite, telemetryEnabled) {
@@ -3502,7 +4120,7 @@ async function installInJsonConfig(configPath, token, region, includeWrite, tele
     if (!includeWrite) env.LEADBAY_MCP_WRITE = "0";
     parsed.mcpServers.leadbay = {
       command: "npx",
-      args: ["-y", "@leadbay/mcp@0.13"],
+      args: ["-y", "@leadbay/mcp@0.16"],
       env
     };
     const tmp = configPath + ".tmp";
@@ -3606,7 +4224,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-2NAFYPXG.js");
+      const { REGIONS } = await import("./dist-7XHTMWB2.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;
@@ -3689,7 +4307,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   process.stderr.write(
     `
 The token was written into client config files but never printed to your terminal.
-Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.13 doctor
+Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.16 doctor
 Restart your MCP client(s) to pick up the new server.
 If you ever leak the token, run \`leadbay-mcp login --email <you> --region <us|fr>\` to mint a fresh one (which invalidates the prior session).
 `