mcp-scraper 0.2.6 → 0.2.8

package/dist/bin/api-server.cjs

@@ -8682,7 +8682,7 @@ function buildYouTubeChannelVideosUrl(channelInput) {
   }
   return `https://www.youtube.com/${handle}/videos`;
 }
-var import_playwright_extra, import_puppeteer_extra_plugin_stealth, import_playwright3, import_sdk4, DESKTOP_USER_AGENT, MOBILE_USER_AGENT, DEFAULT_KERNEL_BROWSER_TIMEOUT_SECONDS, KERNEL_BROWSER_CLOSE_TIMEOUT_MS, KERNEL_SESSION_DELETE_TIMEOUT_MS, BrowserDriver;
+var import_playwright_extra, import_puppeteer_extra_plugin_stealth, import_playwright3, import_sdk4, DESKTOP_USER_AGENT, MOBILE_USER_AGENT, DEFAULT_KERNEL_BROWSER_TIMEOUT_SECONDS, KERNEL_BROWSER_CLOSE_TIMEOUT_MS, KERNEL_SESSION_DELETE_TIMEOUT_MS, DEFAULT_SERP_CHALLENGE_SOLVE_WAIT_MS, SERP_CHALLENGE_SOLVE_POLL_MS, BrowserDriver;
 var init_BrowserDriver = __esm({
   "src/driver/BrowserDriver.ts"() {
     "use strict";
@@ -8698,6 +8698,8 @@ var init_BrowserDriver = __esm({
     DEFAULT_KERNEL_BROWSER_TIMEOUT_SECONDS = 180;
     KERNEL_BROWSER_CLOSE_TIMEOUT_MS = 3e3;
     KERNEL_SESSION_DELETE_TIMEOUT_MS = 5e3;
+    DEFAULT_SERP_CHALLENGE_SOLVE_WAIT_MS = 2500;
+    SERP_CHALLENGE_SOLVE_POLL_MS = 500;
     BrowserDriver = class {
       browser = null;
       context = null;
@@ -8947,20 +8949,20 @@ var init_BrowserDriver = __esm({
           const diag = await this.captureDiagnostics(url);
           throw new ExtractionError(`page.goto failed: ${err.message} | ${diag}`);
         }
-        const captchaCount = await this.page.locator(PAASelectors.captchaMarker).count();
-        if (captchaCount > 0) {
+        if (await this.isSerpChallengeVisible()) {
           await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: false, captchaDetected: true });
-          throw new CaptchaError(this.captchaMessage());
+          const solved = await this.waitForSerpChallengeToClear(navDebug, url);
+          if (!solved) throw new CaptchaError(this.captchaMessage());
         }
         const fastFound = await this.page.waitForSelector(PAASelectors.item, { timeout: 4e3 }).catch(() => null);
         if (fastFound) {
           await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: true, captchaDetected: false });
           return { hasPaa: true };
         }
-        const captchaAfter = await this.page.locator(PAASelectors.captchaMarker).count();
-        if (captchaAfter > 0) {
+        if (await this.isSerpChallengeVisible()) {
           await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: false, captchaDetected: true });
-          throw new CaptchaError(this.captchaMessage());
+          const solved = await this.waitForSerpChallengeToClear(navDebug, url);
+          if (!solved) throw new CaptchaError(this.captchaMessage());
         }
         for (let i = 1; i <= 6; i++) {
           await this.page.evaluate((f) => {
@@ -8976,6 +8978,35 @@ var init_BrowserDriver = __esm({
         await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: false, captchaDetected: false });
         return { hasPaa: false };
       }
+      async isSerpChallengeVisible() {
+        if (!this.page) return false;
+        const captchaCount = await this.page.locator(PAASelectors.captchaMarker).count().catch(() => 0);
+        if (captchaCount > 0) return true;
+        const finalUrl = this.page.url();
+        if (/google\.[^/]+\/sorry\//i.test(finalUrl)) return true;
+        const bodySnippet = await this.page.evaluate(() => {
+          const text = (document.body?.innerText ?? "").replace(/\s+/g, " ").trim();
+          return text.slice(0, 1e3);
+        }).catch(() => "");
+        return /recaptcha|unusual traffic|are you a robot|about this page|detected unusual traffic/i.test(bodySnippet);
+      }
+      async waitForSerpChallengeToClear(navDebug, requestedUrl) {
+        if (!this.kernelClient || !this.page) return false;
+        const waitMs = positiveIntFromEnv("SERP_CHALLENGE_SOLVE_WAIT_MS", DEFAULT_SERP_CHALLENGE_SOLVE_WAIT_MS);
+        const deadline = Date.now() + waitMs;
+        while (Date.now() < deadline) {
+          await this.page.waitForTimeout(Math.min(SERP_CHALLENGE_SOLVE_POLL_MS, Math.max(250, deadline - Date.now())));
+          if (!await this.isSerpChallengeVisible()) {
+            await this.page.waitForTimeout(1e3);
+            if (!await this.isSerpChallengeVisible()) {
+              await this.updateSerpNavigationDebug(navDebug, requestedUrl, { hasPaa: null, captchaDetected: false });
+              return true;
+            }
+          }
+        }
+        await this.updateSerpNavigationDebug(navDebug, requestedUrl, { hasPaa: false, captchaDetected: true });
+        return false;
+      }
       async updateSerpNavigationDebug(navDebug, requestedUrl, state) {
         if (!navDebug || !this.page) return;
         try {
@@ -9023,7 +9054,12 @@ var init_BrowserDriver = __esm({
       async navigateTo(url) {
         try {
           await this.page.goto(url, { waitUntil: "domcontentloaded", timeout: 45e3 });
+          if (/google\.[^/]+\/search\?/i.test(url) && await this.isSerpChallengeVisible()) {
+            const solved = await this.waitForSerpChallengeToClear(null, url);
+            if (!solved) throw new CaptchaError(this.captchaMessage());
+          }
         } catch (err) {
+          if (err instanceof CaptchaError) throw err;
           const diag = await this.captureDiagnostics(url);
           throw new ExtractionError(`page.goto failed: ${err.message} | ${diag}`);
         }
@@ -12584,24 +12620,215 @@ var init_MapsSearchExtractor = __esm({
   }
 });
 
-// src/api/maps-routes.ts
-function mapsErrorResponse(c, msg, errorCode) {
-  const blocked = msg.includes("CAPTCHA") || msg.includes("blocked");
-  return c.json({
-    error: sanitizeVendorName(msg),
-    error_code: blocked ? "captcha_or_blocked" : errorCode,
-    retryable: blocked
-  }, blocked ? 503 : 500);
+// src/maps-search-rotation.ts
+function mapsSearchMaxAttemptsForProxyMode(proxyMode) {
+  return proxyMode === "location" ? MAPS_SEARCH_LOCATION_PROXY_MAX_ATTEMPTS : MAPS_SEARCH_MAX_ATTEMPTS;
+}
+function mapsSearchErrorMessage(err) {
+  return sanitizeVendorName(err instanceof Error ? err.message : String(err));
+}
+function looksLikeProxyTunnelFailure(message) {
+  return /ERR_TUNNEL_CONNECTION_FAILED|ERR_PROXY_CONNECTION_FAILED|ERR_SOCKS_CONNECTION_FAILED|tunnel connection failed|proxy connection failed|transport error: proxy/i.test(message);
+}
+function looksLikeProxyUnavailable(message) {
+  return /proxy unavailable|proxy_unavailable|connection_test_failed|did not return a proxy id|configured fallback/i.test(message);
+}
+function looksLikeBrowserClosed(message) {
+  return /Target page, context or browser has been closed|browser has been closed|context has been closed|page has been closed|browser not found|CDP session closed|Connection closed|WebSocket.*closed|Protocol error.*closed|Browser closed|disconnected/i.test(message);
+}
+function mapsSearchFailureOutcome(err) {
+  if (err instanceof CaptchaError) return "captcha";
+  const message = mapsSearchErrorMessage(err);
+  if (/timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message)) return "timeout";
+  if (looksLikeProxyTunnelFailure(message)) return "proxy_tunnel_failed";
+  if (looksLikeProxyUnavailable(message)) return "proxy_unavailable";
+  if (looksLikeBrowserClosed(message)) return "browser_closed";
+  return "unknown_error";
+}
+function retryableMapsSearchError(err, proxyMode) {
+  if (err instanceof CaptchaError) return true;
+  const message = mapsSearchErrorMessage(err);
+  if (/timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message)) return true;
+  if (looksLikeBrowserClosed(message)) return true;
+  return proxyMode === "location" && (looksLikeProxyTunnelFailure(message) || looksLikeProxyUnavailable(message));
 }
-async function cleanupDisposableProxy(kernelApiKey, proxyId) {
+function suffix(value) {
+  return value ? value.slice(-8) : null;
+}
+function attemptFromDebug(input) {
+  const network = input.debug.networkLocation;
+  const browserSessionId = input.debug.kernel?.sessionId ?? null;
+  const target = input.resolution?.target ?? null;
+  return {
+    attemptNumber: input.attemptIndex + 1,
+    maxAttempts: input.maxAttempts,
+    status: input.status,
+    outcome: input.outcome,
+    willRetry: input.willRetry,
+    durationMs: input.durationMs,
+    resultCount: input.resultCount,
+    error: input.error,
+    proxyMode: input.proxyMode,
+    proxyResolutionSource: input.resolution?.source ?? null,
+    proxyIdSuffix: input.resolution?.proxyIdSuffix ?? null,
+    proxyTargetLevel: target?.level ?? null,
+    proxyTargetLocation: target?.canonicalLocation ?? null,
+    proxyTargetZip: target?.zip ?? null,
+    browserSessionIdSuffix: suffix(browserSessionId),
+    observedIp: network?.ip ?? null,
+    observedCity: network?.city ?? null,
+    observedRegion: network?.region ?? null
+  };
+}
+async function cleanupDisposableProxy(kernelApiKey, proxyId, eventName) {
   if (!kernelApiKey || !proxyId) return;
-  await deleteKernelProxyId(kernelApiKey, proxyId).catch((err) => {
+  try {
+    await deleteKernelProxyId(kernelApiKey, proxyId);
+  } catch (err) {
     console.warn(JSON.stringify({
-      event: "maps_search_proxy_delete_failed",
-      proxy_id_suffix: proxyId.slice(-6),
-      message: err instanceof Error ? err.message : String(err)
+      event: eventName,
+      proxy_id_suffix: suffix(proxyId),
+      message: mapsSearchErrorMessage(err)
     }));
-  });
+  }
+}
+async function runMapsSearchWithRotation(options) {
+  const attempts = [];
+  const maxAttempts = mapsSearchMaxAttemptsForProxyMode(options.proxyMode);
+  const started = Date.now();
+  let lastError = null;
+  for (let attemptIndex = 0; attemptIndex < maxAttempts; attemptIndex += 1) {
+    const attemptStarted = Date.now();
+    const driver = new BrowserDriver();
+    const extractor = new MapsSearchExtractor(driver);
+    const proxyZip = options.proxyZipForAttempt?.(attemptIndex) ?? options.proxyZip;
+    let resolution2 = null;
+    let disposableProxyId;
+    try {
+      resolution2 = await resolveKernelProxyId({
+        kernelApiKey: options.kernelApiKey,
+        proxyMode: options.proxyMode,
+        configuredKernelProxyId: options.kernelProxyId ?? options.configuredKernelProxyId,
+        location: options.location,
+        proxyZip,
+        gl: options.gl,
+        attemptIndex,
+        fresh: options.proxyMode === "location"
+      });
+      disposableProxyId = resolution2.disposableProxyId;
+      const result = await extractor.extract({
+        ...options,
+        proxyZip,
+        kernelProxyId: options.proxyMode === "none" ? void 0 : resolution2.kernelProxyId,
+        kernelProxyResolution: resolution2.resolution
+      });
+      const attempt = attemptFromDebug({
+        attemptIndex,
+        maxAttempts,
+        status: "ok",
+        outcome: "success",
+        willRetry: false,
+        durationMs: Date.now() - attemptStarted,
+        resultCount: result.resultCount,
+        error: null,
+        proxyMode: options.proxyMode,
+        resolution: resolution2.resolution,
+        debug: driver.getDebugSnapshot()
+      });
+      attempts.push(attempt);
+      return {
+        ...result,
+        attempts: attempts.slice(),
+        durationMs: Date.now() - started
+      };
+    } catch (err) {
+      lastError = err;
+      const retryable = retryableMapsSearchError(err, options.proxyMode);
+      const willRetry = attemptIndex < maxAttempts - 1 && retryable;
+      const attempt = attemptFromDebug({
+        attemptIndex,
+        maxAttempts,
+        status: "failed",
+        outcome: mapsSearchFailureOutcome(err),
+        willRetry,
+        durationMs: Date.now() - attemptStarted,
+        resultCount: 0,
+        error: mapsSearchErrorMessage(err),
+        proxyMode: options.proxyMode,
+        resolution: resolution2?.resolution ?? null,
+        debug: driver.getDebugSnapshot()
+      });
+      attempts.push(attempt);
+      console.warn(JSON.stringify({
+        event: options.failureEventName ?? "maps_search_attempt_failed",
+        ...options.logContext,
+        attempt_number: attempt.attemptNumber,
+        max_attempts: attempt.maxAttempts,
+        outcome: attempt.outcome,
+        will_retry: attempt.willRetry,
+        proxy_resolution_source: attempt.proxyResolutionSource,
+        proxy_id_suffix: attempt.proxyIdSuffix,
+        browser_session_id_suffix: attempt.browserSessionIdSuffix,
+        observed_city: attempt.observedCity,
+        observed_region: attempt.observedRegion,
+        message: attempt.error
+      }));
+      if (!willRetry) {
+        throw new MapsSearchRotationError(
+          mapsSearchErrorMessage(err),
+          attempts,
+          retryable,
+          err instanceof CaptchaError ? "captcha_or_blocked" : "maps_search_failed"
+        );
+      }
+    } finally {
+      await cleanupDisposableProxy(options.kernelApiKey, disposableProxyId, "maps_search_proxy_delete_failed");
+      await driver.close();
+    }
+  }
+  throw new MapsSearchRotationError(
+    lastError ? mapsSearchErrorMessage(lastError) : "Maps search failed",
+    attempts,
+    true
+  );
+}
+var MAPS_SEARCH_MAX_ATTEMPTS, MAPS_SEARCH_LOCATION_PROXY_MAX_ATTEMPTS, MapsSearchRotationError;
+var init_maps_search_rotation = __esm({
+  "src/maps-search-rotation.ts"() {
+    "use strict";
+    init_BrowserDriver();
+    init_MapsSearchExtractor();
+    init_errors();
+    init_kernel_proxy_resolver();
+    MAPS_SEARCH_MAX_ATTEMPTS = 3;
+    MAPS_SEARCH_LOCATION_PROXY_MAX_ATTEMPTS = 5;
+    MapsSearchRotationError = class extends Error {
+      constructor(message, attempts, retryable, errorCode = "maps_search_failed") {
+        super(message);
+        this.attempts = attempts;
+        this.retryable = retryable;
+        this.errorCode = errorCode;
+      }
+      attempts;
+      retryable;
+      errorCode;
+      name = "MapsSearchRotationError";
+    };
+  }
+});
+
+// src/api/maps-routes.ts
+function mapsErrorResponse(c, err, errorCode) {
+  const msg = err instanceof Error ? err.message : String(err);
+  const rotationError = err instanceof MapsSearchRotationError ? err : null;
+  const blocked = msg.includes("CAPTCHA") || msg.includes("blocked");
+  const retryable = rotationError?.retryable ?? blocked;
+  return c.json({
+    error: sanitizeVendorName(msg),
+    error_code: rotationError?.errorCode ?? (blocked ? "captcha_or_blocked" : errorCode),
+    retryable,
+    attempts: rotationError?.attempts ?? void 0
+  }, retryable ? 503 : 500);
 }
 var import_hono5, mapsApp;
 var init_maps_routes = __esm({
@@ -12611,13 +12838,12 @@ var init_maps_routes = __esm({
     init_db();
     init_rates();
     init_MapsExtractor();
-    init_MapsSearchExtractor();
     init_BrowserDriver();
     init_schemas3();
     init_api_auth();
     init_errors();
     init_browser_service_env();
-    init_kernel_proxy_resolver();
+    init_maps_search_rotation();
     mapsApp = new import_hono5.Hono();
     mapsApp.post("/search", createApiKeyAuth(), async (c) => {
       const user = c.get("user");
@@ -12636,24 +12862,10 @@ var init_maps_routes = __esm({
         [parsed.data.query, parsed.data.location].filter(Boolean).join(" ")
       );
       if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.maps_search), 402);
-      const driver = new BrowserDriver();
-      const extractor = new MapsSearchExtractor(driver);
-      let disposableProxyId;
       try {
-        const resolution2 = await resolveKernelProxyId({
-          kernelApiKey: parsed.data.kernelApiKey,
-          proxyMode: parsed.data.proxyMode,
-          configuredKernelProxyId: browserServiceProxyId(),
-          location: parsed.data.location,
-          proxyZip: parsed.data.proxyZip,
-          gl: parsed.data.gl,
-          fresh: parsed.data.proxyMode === "location"
-        });
-        disposableProxyId = resolution2.disposableProxyId;
-        const result = await extractor.extract({
+        const result = await runMapsSearchWithRotation({
           ...parsed.data,
-          kernelProxyId: parsed.data.proxyMode === "none" ? void 0 : resolution2.kernelProxyId,
-          kernelProxyResolution: resolution2.resolution
+          configuredKernelProxyId: browserServiceProxyId()
         });
         await logRequestEvent({
           userId: user.id,
@@ -12674,12 +12886,10 @@ var init_maps_routes = __esm({
           status: "failed",
           query: [parsed.data.query, parsed.data.location].filter(Boolean).join(" "),
           location: parsed.data.location,
-          error: msg
+          error: msg,
+          result: err instanceof MapsSearchRotationError ? { attempts: err.attempts } : void 0
         });
-        return mapsErrorResponse(c, msg, "maps_search_failed");
-      } finally {
-        await cleanupDisposableProxy(parsed.data.kernelApiKey, disposableProxyId);
-        await driver.close();
+        return mapsErrorResponse(c, err, "maps_search_failed");
       }
     });
     mapsApp.post("/place", createApiKeyAuth(), async (c) => {
@@ -12886,12 +13096,17 @@ function errorAttemptsSection(body) {
     const browser = debug.browser ?? {};
     const kernel = browser.browserRuntime ?? browser.kernel ?? {};
     const proxyResolution = kernel.proxyResolution ?? {};
-    const network = browser.networkLocation ?? {};
+    const network = browser.networkLocation ?? {
+      ip: attempt.observedIp ?? attempt.observed_ip,
+      city: attempt.observedCity ?? attempt.observed_city,
+      region: attempt.observedRegion ?? attempt.observed_region
+    };
     const nav = browser.serpNavigation ?? {};
     const geo = [network.ip, network.city, network.region].filter(Boolean).join(" / ") || "geo unknown";
-    const sessionId = attempt.browser_session_id ?? attempt.kernel_session_id ?? kernel.sessionId ?? "unknown";
+    const sessionId = attempt.browser_session_id ?? attempt.browserSessionIdSuffix ?? attempt.kernel_session_id ?? kernel.sessionId ?? "unknown";
     const cleanupSucceeded2 = attempt.session_cleanup_succeeded ?? attempt.kernel_delete_succeeded;
-    return `- Attempt ${attempt.attempt_number ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${sessionId} \xB7 proxy ${debug.request?.proxyMode ?? kernel.proxyMode ?? "unknown"}${proxyResolution.source ? `/${proxyResolution.source}` : ""} \xB7 ${geo} \xB7 CAPTCHA ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 cleanup ${cleanupSucceeded2 === true ? "yes" : cleanupSucceeded2 === false ? "no" : "unknown"}`;
+    const proxySource = proxyResolution.source ?? attempt.proxyResolutionSource;
+    return `- Attempt ${attempt.attempt_number ?? attempt.attemptNumber ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${sessionId} \xB7 proxy ${debug.request?.proxyMode ?? kernel.proxyMode ?? attempt.proxyMode ?? "unknown"}${proxySource ? `/${proxySource}` : ""} \xB7 ${geo} \xB7 CAPTCHA ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 cleanup ${cleanupSucceeded2 === true ? "yes" : cleanupSucceeded2 === false ? "no" : "unknown"}`;
   });
   return `
 
@@ -13352,6 +13567,29 @@ ${rows}`,
     }
   };
 }
+function normalizeMapsAttempts(value) {
+  const attempts = Array.isArray(value) ? value : [];
+  return attempts.map((attempt, index) => ({
+    attemptNumber: attempt.attemptNumber ?? attempt.attempt_number ?? index + 1,
+    maxAttempts: attempt.maxAttempts ?? attempt.max_attempts ?? attempts.length,
+    status: attempt.status === "ok" ? "ok" : "failed",
+    outcome: attempt.outcome ?? attempt.status ?? "unknown",
+    willRetry: attempt.willRetry ?? attempt.will_retry ?? false,
+    durationMs: attempt.durationMs ?? attempt.duration_ms ?? 0,
+    resultCount: attempt.resultCount ?? attempt.result_count ?? 0,
+    error: attempt.error ? sanitizeVendorText(attempt.error) : null,
+    proxyMode: attempt.proxyMode ?? attempt.proxy_mode ?? "location",
+    proxyResolutionSource: attempt.proxyResolutionSource ?? attempt.proxy_resolution_source ?? null,
+    proxyIdSuffix: attempt.proxyIdSuffix ?? attempt.proxy_id_suffix ?? null,
+    proxyTargetLevel: attempt.proxyTargetLevel ?? attempt.proxy_target_level ?? null,
+    proxyTargetLocation: attempt.proxyTargetLocation ?? attempt.proxy_target_location ?? null,
+    proxyTargetZip: attempt.proxyTargetZip ?? attempt.proxy_target_zip ?? null,
+    browserSessionIdSuffix: attempt.browserSessionIdSuffix ?? attempt.browser_session_id ?? null,
+    observedIp: attempt.observedIp ?? attempt.observed_ip ?? null,
+    observedCity: attempt.observedCity ?? attempt.observed_city ?? null,
+    observedRegion: attempt.observedRegion ?? attempt.observed_region ?? null
+  }));
+}
 function formatCreditsInfo(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -13424,6 +13662,8 @@ function formatMapsSearch(raw, input) {
   const searchQuery = d.searchQuery ?? [input.query, input.location].filter(Boolean).join(" ");
   const requestedMax = d.requestedMaxResults ?? input.maxResults ?? 10;
   const durationMs = d.durationMs;
+  const attempts = normalizeMapsAttempts(d.attempts);
+  const lastAttempt = attempts.at(-1);
   const rows = results.map((r) => {
     const rating = [r.rating, r.reviewCount ? `(${r.reviewCount})` : null].filter(Boolean).join(" ");
     return `| ${r.position} | ${cell(r.name)} | ${cell(r.category)} | ${cell(rating)} | ${cell(r.address)} | ${r.cidDecimal ? `\`${r.cidDecimal}\`` : "\u2014"} | ${r.websiteUrl ? `[site](${r.websiteUrl})` : "\u2014"} | [maps](${r.placeUrl}) |`;
@@ -13438,6 +13678,7 @@ ${meta}`;
   const full = [
     `# Google Maps Search: "${searchQuery}"`,
     `**Returned:** ${results.length} profile candidate${results.length === 1 ? "" : "s"} \xB7 **Requested max:** ${requestedMax} \xB7 **Limit:** 50`,
+    attempts.length ? `**Attempts:** ${attempts.length}/${lastAttempt?.maxAttempts ?? attempts.length} \xB7 **Proxy:** ${lastAttempt?.proxyMode ?? "unknown"}${lastAttempt?.proxyResolutionSource ? `/${lastAttempt.proxyResolutionSource}` : ""} \xB7 **Observed:** ${[lastAttempt?.observedCity, lastAttempt?.observedRegion].filter(Boolean).join(", ") || "unknown"}` : null,
     `
 ## Results
 | # | Name | Category | Rating | Address | CID | Website | Maps |
@@ -13461,6 +13702,7 @@ ${rows}`,
       requestedMaxResults: requestedMax,
       resultCount: results.length,
       results: normalizedResults,
+      attempts,
       durationMs: durationMs ?? 0
     }
   };
@@ -13471,6 +13713,7 @@ function formatDirectoryWorkflow(raw, input) {
   const d = parsed.data;
   const cities = (d.cities ?? []).map((city) => ({
     ...city,
+    attempts: normalizeMapsAttempts(city.attempts),
     results: city.results.map((result) => ({
       ...result,
       phone: result.phone ?? null,
@@ -13934,36 +14177,9 @@ var init_location_db = __esm({
 });
 
 // src/directory/directory-workflow.ts
-async function cleanupDisposableProxy2(kernelApiKey, proxyId) {
-  if (!kernelApiKey || !proxyId) return;
-  try {
-    await deleteKernelProxyId(kernelApiKey, proxyId);
-  } catch (err) {
-    console.warn(JSON.stringify({
-      event: "directory_workflow_proxy_delete_failed",
-      proxy_id_suffix: proxyId.slice(-6),
-      message: err instanceof Error ? err.message : String(err)
-    }));
-  }
-}
-function maxAttemptsForProxyMode(proxyMode) {
-  return proxyMode === "location" ? DIRECTORY_LOCATION_PROXY_MAX_ATTEMPTS : DIRECTORY_MAX_ATTEMPTS;
-}
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
-function looksLikeProxyTunnelFailure(message) {
-  return /ERR_TUNNEL_CONNECTION_FAILED|ERR_PROXY_CONNECTION_FAILED|ERR_SOCKS_CONNECTION_FAILED|tunnel connection failed|proxy connection failed|transport error: proxy/i.test(message);
-}
-function looksLikeProxyUnavailable(message) {
-  return /proxy unavailable|proxy_unavailable|connection_test_failed|did not return a proxy id|configured fallback/i.test(message);
-}
-function retryableCitySearchError(err, proxyMode) {
-  if (err instanceof CaptchaError) return true;
-  const message = errorMessage(err);
-  if (/timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message)) return true;
-  return proxyMode === "location" && (looksLikeProxyTunnelFailure(message) || looksLikeProxyUnavailable(message));
-}
 function proxyZipForAttempt(options, market, attemptIndex) {
   if (options.proxyZip) return options.proxyZip;
   if (!market.zips.length) return void 0;
@@ -13982,25 +14198,10 @@ async function mapLimit(items, limit, fn) {
   await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
   return out;
 }
-async function searchCityAttempt(options, market, attemptIndex) {
-  const driver = new BrowserDriver();
-  const extractor = new MapsSearchExtractor(driver);
-  const start = Date.now();
-  let disposableProxyId;
+async function searchCity(options, market) {
+  const started = Date.now();
   try {
-    const proxyZip = proxyZipForAttempt(options, market, attemptIndex);
-    const resolution2 = await resolveKernelProxyId({
-      kernelApiKey: options.kernelApiKey,
-      proxyMode: options.proxyMode,
-      configuredKernelProxyId: browserServiceProxyId(),
-      location: market.location,
-      proxyZip,
-      gl: options.gl,
-      attemptIndex,
-      fresh: options.proxyMode === "location"
-    });
-    disposableProxyId = resolution2.disposableProxyId;
-    const result = await extractor.extract({
+    const result = await runMapsSearchWithRotation({
       query: options.query,
       location: market.location,
       gl: options.gl,
@@ -14008,11 +14209,16 @@ async function searchCityAttempt(options, market, attemptIndex) {
       maxResults: options.maxResultsPerCity,
       headless: options.headless,
       kernelApiKey: options.kernelApiKey,
-      kernelProxyId: options.proxyMode === "none" ? void 0 : resolution2.kernelProxyId,
-      kernelProxyResolution: resolution2.resolution,
       proxyMode: options.proxyMode,
-      proxyZip,
-      debug: options.debug
+      proxyZip: options.proxyZip,
+      debug: options.debug,
+      configuredKernelProxyId: browserServiceProxyId(),
+      proxyZipForAttempt: (attemptIndex) => proxyZipForAttempt(options, market, attemptIndex),
+      failureEventName: "directory_workflow_city_attempt_failed",
+      logContext: {
+        city: market.city,
+        state: market.state
+      }
     });
     return {
       city: market.city,
@@ -14028,50 +14234,29 @@ async function searchCityAttempt(options, market, attemptIndex) {
       error: null,
       resultCount: result.resultCount,
       durationMs: result.durationMs,
+      attempts: result.attempts ?? [],
       results: result.results
     };
-  } finally {
-    await cleanupDisposableProxy2(options.kernelApiKey, disposableProxyId);
-  }
-}
-async function searchCity(options, market) {
-  const started = Date.now();
-  const maxAttempts = maxAttemptsForProxyMode(options.proxyMode);
-  let lastError = null;
-  for (let attemptIndex = 0; attemptIndex < maxAttempts; attemptIndex += 1) {
-    try {
-      return await searchCityAttempt(options, market, attemptIndex);
-    } catch (err) {
-      lastError = err;
-      const willRetry = attemptIndex < maxAttempts - 1 && retryableCitySearchError(err, options.proxyMode);
-      console.warn(JSON.stringify({
-        event: "directory_workflow_city_attempt_failed",
-        city: market.city,
-        state: market.state,
-        attempt_number: attemptIndex + 1,
-        max_attempts: maxAttempts,
-        will_retry: willRetry,
-        message: errorMessage(err)
-      }));
-      if (!willRetry) break;
-    }
+  } catch (err) {
+    const attempts = err instanceof MapsSearchRotationError ? err.attempts : [];
+    return {
+      city: market.city,
+      state: market.state,
+      location: market.location,
+      cityKey: market.cityKey,
+      censusName: market.censusName,
+      population: market.population,
+      populationYear: market.populationYear,
+      zips: market.zips,
+      counties: market.counties,
+      status: "failed",
+      error: errorMessage(err),
+      resultCount: 0,
+      durationMs: Date.now() - started,
+      attempts,
+      results: []
+    };
   }
-  return {
-    city: market.city,
-    state: market.state,
-    location: market.location,
-    cityKey: market.cityKey,
-    censusName: market.censusName,
-    population: market.population,
-    populationYear: market.populationYear,
-    zips: market.zips,
-    counties: market.counties,
-    status: "failed",
-    error: lastError ? errorMessage(lastError) : "City Maps search failed",
-    resultCount: 0,
-    durationMs: Date.now() - started,
-    results: []
-  };
 }
 function csvRowsFor(result) {
   const rows = [];
@@ -14206,23 +14391,18 @@ async function runDirectoryWorkflowFromPlan(options, plan) {
   const csvPath = options.saveCsv ? await saveDirectoryCsv(base) : null;
   return { ...base, csvPath };
 }
-var import_promises5, import_node_path6, import_zod18, DIRECTORY_MAX_ATTEMPTS, DIRECTORY_LOCATION_PROXY_MAX_ATTEMPTS, DirectoryWorkflowOptionsSchema;
+var import_promises5, import_node_path6, import_zod18, DirectoryWorkflowOptionsSchema;
 var init_directory_workflow = __esm({
   "src/directory/directory-workflow.ts"() {
     "use strict";
     import_promises5 = require("fs/promises");
     import_node_path6 = require("path");
     import_zod18 = require("zod");
-    init_MapsSearchExtractor();
-    init_BrowserDriver();
     init_mcp_response_formatter();
     init_browser_service_env();
-    init_kernel_proxy_resolver();
-    init_errors();
+    init_maps_search_rotation();
     init_csv();
     init_location_db();
-    DIRECTORY_MAX_ATTEMPTS = 3;
-    DIRECTORY_LOCATION_PROXY_MAX_ATTEMPTS = 5;
     DirectoryWorkflowOptionsSchema = import_zod18.z.object({
       query: import_zod18.z.string().min(1),
       state: import_zod18.z.string().min(2).default("TN"),
@@ -16034,7 +16214,7 @@ function classifyAttemptResult(result) {
 function errorMessage2(err) {
   return err instanceof Error ? err.message : String(err);
 }
-function maxAttemptsForProxyMode2(proxyMode) {
+function maxAttemptsForProxyMode(proxyMode) {
   return proxyMode === "location" ? LOCATION_PROXY_MAX_ATTEMPTS : MAX_ATTEMPTS2;
 }
 function looksLikeProxyTunnelFailure2(message) {
@@ -16061,7 +16241,7 @@ function stripInternalDebug(result, keepDebug) {
   delete diagnostics.debug;
   return { ...result, diagnostics };
 }
-async function cleanupDisposableProxy3(kernelApiKey, proxyId) {
+async function cleanupDisposableProxy2(kernelApiKey, proxyId) {
   if (!kernelApiKey || !proxyId) return;
   try {
     await deleteKernelProxyId(kernelApiKey, proxyId);
@@ -16146,7 +16326,7 @@ async function harvest(rawOptions) {
   };
   const requestedDebug = typeof raw.debug === "boolean" ? raw.debug : false;
   const needsLocationEvidence = proxyMode === "location" && Boolean(proxyOpts.location);
-  const maxAttempts = maxAttemptsForProxyMode2(proxyMode);
+  const maxAttempts = maxAttemptsForProxyMode(proxyMode);
   const serializer = new OutputSerializer();
   let lastError = null;
   for (let i = 0; i < maxAttempts; i++) {
@@ -16223,7 +16403,7 @@ async function harvest(rawOptions) {
           debug: attempt.debug,
           completedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
-        await cleanupDisposableProxy3(kernelApiKey, resolution2.disposableProxyId);
+        await cleanupDisposableProxy2(kernelApiKey, resolution2.disposableProxyId);
         lastError = err;
         if (willRetry) continue;
         break;
@@ -16254,7 +16434,7 @@ async function harvest(rawOptions) {
           debug: attempt.debug,
           completedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
-        await cleanupDisposableProxy3(kernelApiKey, resolution2.disposableProxyId);
+        await cleanupDisposableProxy2(kernelApiKey, resolution2.disposableProxyId);
         lastError = err;
         if (willRetry) continue;
         break;
@@ -16274,7 +16454,7 @@ async function harvest(rawOptions) {
         debug: attempt.debug,
         completedAt: (/* @__PURE__ */ new Date()).toISOString()
       });
-      await cleanupDisposableProxy3(kernelApiKey, resolution2.disposableProxyId);
+      await cleanupDisposableProxy2(kernelApiKey, resolution2.disposableProxyId);
       if (attemptOptions.format === "json" || attemptOptions.format === "both") {
         await serializer.writeJSON(finalResult, attemptOptions.outputDir);
       }
@@ -17082,12 +17262,12 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.2.6";
+    PACKAGE_VERSION = "0.2.8";
   }
 });
 
 // src/mcp/mcp-tool-schemas.ts
-var import_zod20, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod20, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -17099,7 +17279,7 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod20.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
       hl: import_zod20.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
       device: import_zod20.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt and retries CAPTCHA, proxy tunnel failure, and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
       proxyZip: import_zod20.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
       debug: import_zod20.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
     };
@@ -17158,7 +17338,7 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod20.z.string().length(2).default("us").describe("Google country code inferred from location."),
       hl: import_zod20.z.string().length(2).default("en").describe("Language inferred from user request."),
       maxResults: import_zod20.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
-      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; it creates a fresh residential proxy ID when the browser service is available. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts. Use configured for the server proxy ID, and none only for local direct-network debugging."),
       proxyZip: import_zod20.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
       debug: import_zod20.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
     };
@@ -17173,7 +17353,7 @@ var init_mcp_tool_schemas = __esm({
       includeZipGroups: import_zod20.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
       usZipsCsvPath: import_zod20.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
       saveCsv: import_zod20.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
-      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; it creates fresh residential proxy IDs when the browser service is available. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts per city. Use configured for the server proxy ID, and none only for local direct-network debugging."),
       proxyZip: import_zod20.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
       debug: import_zod20.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
     };
@@ -17196,6 +17376,26 @@ var init_mcp_tool_schemas = __esm({
       notes: import_zod20.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
     };
     NullableString = import_zod20.z.string().nullable();
+    MapsSearchAttemptOutput = import_zod20.z.object({
+      attemptNumber: import_zod20.z.number().int().min(1),
+      maxAttempts: import_zod20.z.number().int().min(1),
+      status: import_zod20.z.enum(["ok", "failed"]),
+      outcome: import_zod20.z.string(),
+      willRetry: import_zod20.z.boolean(),
+      durationMs: import_zod20.z.number().int().min(0),
+      resultCount: import_zod20.z.number().int().min(0),
+      error: NullableString,
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]),
+      proxyResolutionSource: import_zod20.z.enum(["disabled", "location_reused", "location_created", "configured_fallback", "unavailable"]).nullable(),
+      proxyIdSuffix: NullableString,
+      proxyTargetLevel: import_zod20.z.enum(["zip", "city", "state"]).nullable(),
+      proxyTargetLocation: NullableString,
+      proxyTargetZip: NullableString,
+      browserSessionIdSuffix: NullableString,
+      observedIp: NullableString,
+      observedCity: NullableString,
+      observedRegion: NullableString
+    });
     MapsSearchOutputSchema = {
       query: import_zod20.z.string(),
       location: import_zod20.z.string().nullable(),
@@ -17220,6 +17420,7 @@ var init_mcp_tool_schemas = __esm({
         directionsUrl: NullableString,
         metadata: import_zod20.z.array(import_zod20.z.string())
       })),
+      attempts: import_zod20.z.array(MapsSearchAttemptOutput),
       durationMs: import_zod20.z.number().int().min(0)
     };
     DirectoryMapsBusinessOutput = import_zod20.z.object({
@@ -17266,6 +17467,7 @@ var init_mcp_tool_schemas = __esm({
         error: NullableString,
         resultCount: import_zod20.z.number().int().min(0),
         durationMs: import_zod20.z.number().int().min(0),
+        attempts: import_zod20.z.array(MapsSearchAttemptOutput),
         results: import_zod20.z.array(DirectoryMapsBusinessOutput)
       })),
       durationMs: import_zod20.z.number().int().min(0)
@@ -17482,7 +17684,7 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod20.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
       hl: import_zod20.z.string().default("en").describe("Google interface/content language inferred from user request."),
       device: import_zod20.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt and retries CAPTCHA, proxy tunnel failure, and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
       proxyZip: import_zod20.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
       debug: import_zod20.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
       pages: import_zod20.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
@@ -17493,7 +17695,7 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod20.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
       hl: import_zod20.z.string().default("en").describe("Google interface/content language inferred from the user request."),
       device: import_zod20.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
-      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt and retries CAPTCHA, proxy tunnel failure, and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
       proxyZip: import_zod20.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting when a precise city-center or ZIP proxy is needed. With proxyMode location this ZIP is used for each fresh proxy attempt."),
       pages: import_zod20.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
       debug: import_zod20.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
@@ -17913,14 +18115,14 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   if (savesReports) registerSavedReportResources(server);
   server.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). For US local SERPs, leave proxyMode as location so the service uses fresh residential proxy IDs across retries and rejects wrong-location evidence instead of returning a bad market. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
+    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). For US local SERPs, leave proxyMode as location so the service uses fresh residential proxy IDs across retries, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear or the market evidence is wrong. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
     inputSchema: HarvestPaaInputSchema,
     outputSchema: HarvestPaaOutputSchema,
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
   server.registerTool("search_serp", {
     title: "Google SERP Lookup",
-    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. For US city/state rankings, keep proxyMode as location and pass proxyZip when a city-center ZIP is known; location mode uses fresh residential proxy IDs and retries CAPTCHA, proxy tunnel failures, and wrong-location evidence before returning."),
+    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. For US city/state rankings, keep proxyMode as location and pass proxyZip when a city-center ZIP is known; location mode uses fresh residential proxy IDs, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear, the proxy tunnel fails, or location evidence is wrong."),
     inputSchema: SearchSerpInputSchema,
     outputSchema: SearchSerpOutputSchema,
     annotations: liveWebToolAnnotations("Google SERP Lookup")
@@ -17988,14 +18190,14 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." For US city/state Maps searches, keep proxyMode as location so the browser service can create a fresh residential proxy ID for that market; pass proxyZip only when a specific ZIP or city-center ZIP is known. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, and profile metadata. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
+    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." For US city/state Maps searches, keep proxyMode as location so the browser service creates a fresh residential proxy ID and browser session for the market; retryable failures rotate to a new proxy and new browser session for up to 5 attempts. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
     inputSchema: MapsSearchInputSchema,
     outputSchema: MapsSearchOutputSchema,
     annotations: liveWebToolAnnotations("Google Maps Business Search")
   }, async (input) => formatMapsSearch(await executor.mapsSearch(input), input));
   server.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Use concurrency up to 5 for parallel city sessions. Keep proxyMode as location so each city can use a fresh residential proxy ID when the browser service is available; retryable city failures use fresh proxies across attempts. Saved CSV rows include source_location, result_position, business_name, review_stars, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. This workflow captures star ratings from Maps list cards, not profile review counts; use maps_place_intel only when a selected profile needs deeper review details. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
+    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Use concurrency up to 5 for parallel city sessions. Keep proxyMode as location so each city search creates fresh residential proxy IDs and browser sessions; retryable city failures rotate to a new proxy and new browser session for up to 5 attempts. Saved CSV rows include source_location, result_position, business_name, review_stars, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. This workflow captures star ratings from Maps list cards, not profile review counts; use maps_place_intel only when a selected profile needs deeper review details. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
     inputSchema: DirectoryWorkflowInputSchema,
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
@@ -18183,7 +18385,7 @@ async function requireMcpCallerKey(c) {
 function registerSerpIntelligenceCaptureTools(server, executor) {
   server.registerTool("capture_serp_snapshot", {
     title: "SERP Intelligence Snapshot",
-    description: "Capture a structured SERP Intelligence Google snapshot through POST /serp-intelligence/capture, the same product capture path used by Phoenix. Split query from location, infer gl/hl, use proxyMode location for localized US residential evidence; location mode creates fresh proxy IDs across retries and rejects wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging. Set debug true when investigating location evidence, proxy behavior, CAPTCHA, or capture reliability.",
+    description: "Capture a structured SERP Intelligence Google snapshot through POST /serp-intelligence/capture, the same product capture path used by Phoenix. Split query from location, infer gl/hl, use proxyMode location for localized US residential evidence; location mode creates fresh proxy IDs across retries, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear or location evidence is wrong. Use configured only for the static residential proxy, and none only for direct-network debugging. Set debug true when investigating location evidence, proxy behavior, CAPTCHA, or capture reliability.",
     inputSchema: CaptureSerpSnapshotInputSchema,
     annotations: liveWebToolAnnotations("SERP Intelligence Snapshot")
   }, async (input) => executor.captureSerpSnapshot(input));
@@ -18351,18 +18553,26 @@ async function recordAction(input) {
 async function recordReplayStart(input) {
   const db = getDb();
   await db.execute({
-    sql: `INSERT INTO browser_agent_replays (replay_id, session_id, view_url, label)
-          VALUES (?, ?, ?, ?)`,
-    args: [input.replayId, input.sessionId, input.viewUrl, input.label]
+    sql: `INSERT INTO browser_agent_replays (replay_id, session_id, view_url, label, started_at)
+          VALUES (?, ?, ?, ?, ?)`,
+    args: [input.replayId, input.sessionId, input.viewUrl, input.label, (/* @__PURE__ */ new Date()).toISOString()]
   });
 }
 async function recordReplayStop(replayId, viewUrl) {
   const db = getDb();
   await db.execute({
-    sql: `UPDATE browser_agent_replays SET stopped_at = datetime('now'), view_url = COALESCE(?, view_url) WHERE replay_id = ?`,
-    args: [viewUrl, replayId]
+    sql: `UPDATE browser_agent_replays SET stopped_at = ?, view_url = COALESCE(?, view_url) WHERE replay_id = ?`,
+    args: [(/* @__PURE__ */ new Date()).toISOString(), viewUrl, replayId]
   });
 }
+async function getActiveReplayRow(sessionId) {
+  const db = getDb();
+  const res = await db.execute({
+    sql: `SELECT * FROM browser_agent_replays WHERE session_id = ? AND stopped_at IS NULL ORDER BY started_at DESC LIMIT 1`,
+    args: [sessionId]
+  });
+  return res.rows[0] ?? null;
+}
 async function listReplayRows(sessionId) {
   const db = getDb();
   const res = await db.execute({
@@ -18482,7 +18692,13 @@ async function readPage(cdpWsUrl) {
           role: el2.getAttribute("role") || el2.tagName.toLowerCase(),
           name,
           x: Math.round(r.left + r.width / 2),
-          y: Math.round(r.top + r.height / 2)
+          y: Math.round(r.top + r.height / 2),
+          left: Math.round(r.left),
+          top: Math.round(r.top),
+          width: Math.round(r.width),
+          height: Math.round(r.height),
+          right: Math.round(r.right),
+          bottom: Math.round(r.bottom)
         });
       }
       const text = (document.body?.innerText || "").replace(/\n{3,}/g, "\n\n").trim().slice(0, 6e3);
@@ -18492,13 +18708,168 @@ async function readPage(cdpWsUrl) {
       url,
       title,
       text: data.text,
-      elements: data.els.map((e, i) => ({ ref: i + 1, role: e.role, name: e.name, x: e.x, y: e.y }))
+      elements: data.els.map((e, i) => ({
+        ref: i + 1,
+        role: e.role,
+        name: e.name,
+        x: e.x,
+        y: e.y,
+        left: e.left,
+        top: e.top,
+        width: e.width,
+        height: e.height,
+        right: e.right,
+        bottom: e.bottom
+      }))
     };
   } finally {
     await browser.close().catch(() => {
     });
   }
 }
+async function locatePageTargets(cdpWsUrl, targets) {
+  const browser = await import_playwright4.chromium.connectOverCDP(cdpWsUrl);
+  try {
+    const context = browser.contexts()[0] ?? await browser.newContext();
+    const page = context.pages()[0] ?? await context.newPage();
+    const url = page.url();
+    const title = await page.title().catch(() => "");
+    await page.evaluate(() => {
+      ;
+      globalThis.__name = (target) => target;
+    }).catch(() => {
+    });
+    const data = await page.evaluate((rawTargets) => {
+      const normalize = (value) => value.replace(/\s+/g, " ").trim();
+      const isVisibleRect = (r) => r.width >= 1 && r.height >= 1 && r.bottom >= 0 && r.right >= 0 && r.top <= window.innerHeight && r.left <= window.innerWidth;
+      const roleOf = (el2) => el2.getAttribute("role") || el2.tagName.toLowerCase();
+      const nameOf = (el2) => {
+        const e = el2;
+        return normalize(
+          e.getAttribute("aria-label") || e.placeholder || e.innerText || e.getAttribute("value") || e.getAttribute("title") || ""
+        ).slice(0, 160);
+      };
+      const textOf = (el2) => normalize(el2.innerText || el2.textContent || "").slice(0, 500);
+      const unionRects = (rects) => {
+        const visible = rects.filter(isVisibleRect);
+        if (!visible.length) return null;
+        const left = Math.min(...visible.map((r) => r.left));
+        const top = Math.min(...visible.map((r) => r.top));
+        const right = Math.max(...visible.map((r) => r.right));
+        const bottom = Math.max(...visible.map((r) => r.bottom));
+        return {
+          left,
+          top,
+          right,
+          bottom,
+          width: right - left,
+          height: bottom - top,
+          x: left,
+          y: top,
+          toJSON: () => ({})
+        };
+      };
+      const elementPayload = (el2, rect) => ({
+        role: roleOf(el2),
+        tag: el2.tagName.toLowerCase(),
+        name: nameOf(el2),
+        text: textOf(el2),
+        x: Math.round(rect.left + rect.width / 2),
+        y: Math.round(rect.top + rect.height / 2),
+        left: Math.round(rect.left),
+        top: Math.round(rect.top),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        right: Math.round(rect.right),
+        bottom: Math.round(rect.bottom)
+      });
+      const selectorMatches = (selector) => {
+        const nodes = Array.from(document.querySelectorAll(selector));
+        return nodes.map((el2) => ({ el: el2, rect: el2.getBoundingClientRect() })).filter((item) => isVisibleRect(item.rect));
+      };
+      const textMatches = (needle, match) => {
+        const wanted = normalize(needle);
+        const wantedLower = wanted.toLowerCase();
+        if (!wantedLower) return [];
+        const matches = [];
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+        let node = walker.nextNode();
+        while (node) {
+          const raw = node.textContent || "";
+          const normalizedRaw = normalize(raw);
+          const rawLower = raw.toLowerCase();
+          const normalizedLower = normalizedRaw.toLowerCase();
+          const ok = match === "exact" ? normalizedLower === wantedLower : normalizedLower.includes(wantedLower);
+          if (ok) {
+            const start = match === "exact" ? 0 : rawLower.indexOf(wantedLower);
+            const parent = node.parentElement;
+            if (parent && start >= 0) {
+              try {
+                const range = document.createRange();
+                range.setStart(node, Math.min(start, raw.length));
+                range.setEnd(node, Math.min(raw.length, start + needle.length));
+                const rect = unionRects(Array.from(range.getClientRects()));
+                range.detach();
+                if (rect) matches.push({ el: parent, rect });
+              } catch {
+                const rect = parent.getBoundingClientRect();
+                if (isVisibleRect(rect)) matches.push({ el: parent, rect });
+              }
+            }
+          }
+          node = walker.nextNode();
+        }
+        if (matches.length) return matches;
+        const fallback = Array.from(document.querySelectorAll("body *")).map((el2) => ({ el: el2, rect: el2.getBoundingClientRect(), text: textOf(el2) })).filter((item) => isVisibleRect(item.rect)).filter((item) => {
+          const value = item.text.toLowerCase();
+          return match === "exact" ? value === wantedLower : value.includes(wantedLower);
+        }).sort((a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height);
+        return fallback.map(({ el: el2, rect }) => ({ el: el2, rect }));
+      };
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio || 1
+      };
+      const results = rawTargets.map((target) => {
+        const index = Math.max(0, Math.floor(target.index ?? 0));
+        const match = target.match === "exact" ? "exact" : "contains";
+        try {
+          const selector = target.selector?.trim();
+          const text = target.text?.trim();
+          const candidates = selector ? selectorMatches(selector) : text ? textMatches(text, match) : [];
+          const selected = candidates[index];
+          return {
+            name: target.name ?? null,
+            selector: selector || null,
+            text: text || null,
+            match,
+            index,
+            found: Boolean(selected),
+            element: selected ? elementPayload(selected.el, selected.rect) : null,
+            ...selected ? {} : { error: "target not found in current viewport" }
+          };
+        } catch (err) {
+          return {
+            name: target.name ?? null,
+            selector: target.selector ?? null,
+            text: target.text ?? null,
+            match,
+            index,
+            found: false,
+            element: null,
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      });
+      return { viewport, targets: results };
+    }, targets);
+    return { url, title, viewport: data.viewport, targets: data.targets };
+  } finally {
+    await browser.close().catch(() => {
+    });
+  }
+}
 async function replayStart(runtimeSessionId) {
   const k = client();
   const res = await k.browsers.replays.start(runtimeSessionId);
@@ -18561,6 +18932,22 @@ function failure(err) {
   const msg = err instanceof Error ? err.message : String(err);
   return { error: sanitizeVendorName(msg) };
 }
+function parseAgentDate(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  if (Number.isFinite(parsed)) return parsed;
+  const legacyParsed = Date.parse(`${value.replace(" ", "T")}Z`);
+  return Number.isFinite(legacyParsed) ? legacyParsed : null;
+}
+function replayClock(row) {
+  if (!row) return null;
+  const startedAtMs = parseAgentDate(row.started_at);
+  return {
+    replay_id: row.replay_id,
+    started_at: row.started_at,
+    replay_elapsed_seconds: startedAtMs == null ? null : Math.max(0, (Date.now() - startedAtMs) / 1e3)
+  };
+}
 function replayDownloadUrl(sessionId, replayId) {
   return `/agent/sessions/${encodeURIComponent(sessionId)}/replays/${encodeURIComponent(replayId)}/download`;
 }
@@ -18671,13 +19058,15 @@ function buildBrowserAgentRoutes() {
       }
       await charge(row.id, user.id, t0);
       await recordAction({ sessionId: row.id, type: "screenshot", params: null, ok: true });
+      const activeReplay = await getActiveReplayRow(row.id);
       return c.json({
         image_base64: shot.base64,
         mime_type: shot.mimeType,
         url: page?.url ?? null,
         title: page?.title ?? null,
         elements: page?.elements ?? [],
-        text: page?.text ?? null
+        text: page?.text ?? null,
+        replay: replayClock(activeReplay)
       });
     } catch (err) {
       await charge(row.id, user.id, t0);
@@ -18694,7 +19083,8 @@ function buildBrowserAgentRoutes() {
       const page = await readPage(row.cdp_ws_url);
       await charge(row.id, user.id, t0);
       await recordAction({ sessionId: row.id, type: "read", params: null, ok: true });
-      return c.json(page);
+      const activeReplay = await getActiveReplayRow(row.id);
+      return c.json({ ...page, replay: replayClock(activeReplay) });
     } catch (err) {
       await charge(row.id, user.id, t0);
       return c.json(failure(err), 502);
@@ -18723,6 +19113,27 @@ function buildBrowserAgentRoutes() {
       return c.json(failure(err), 502);
     }
   });
+  app2.post("/sessions/:id/locate", async (c) => {
+    const user = c.get("user");
+    const row = await loadOpenSession(c.req.param("id"), user.id);
+    if (!row) return c.json({ error: "not found" }, 404);
+    const body = await c.req.json().catch(() => ({}));
+    const rawTargets = Array.isArray(body.targets) ? body.targets : [];
+    const targets = rawTargets.filter((value) => value && typeof value === "object").slice(0, 20).map((value) => value);
+    if (!targets.length) return c.json({ error: "targets is required" }, 400);
+    const t0 = Date.now();
+    try {
+      const result = await locatePageTargets(row.cdp_ws_url, targets);
+      await charge(row.id, user.id, t0);
+      await recordAction({ sessionId: row.id, type: "locate", params: { targets: targets.length }, ok: true });
+      const activeReplay = await getActiveReplayRow(row.id);
+      return c.json({ ...result, replay: replayClock(activeReplay) });
+    } catch (err) {
+      await charge(row.id, user.id, t0);
+      await recordAction({ sessionId: row.id, type: "locate", params: { targets: targets.length }, ok: false, error: String(err) });
+      return c.json(failure(err), 502);
+    }
+  });
   app2.post("/sessions/:id/type", async (c) => {
     const user = c.get("user");
     const row = await loadOpenSession(c.req.param("id"), user.id);