crawlforge-mcp-server 5.1.0 → 5.2.1

package/CLAUDE.md

@@ -62,7 +62,7 @@ These guidelines are working if: fewer unnecessary changes in diffs, fewer rewri
 
 CrawlForge MCP Server - A professional MCP (Model Context Protocol) server providing 28 web scraping, crawling, and content processing tools (5 inline + 23 advanced).
 
-**Current Version:** 5.1.0
+**Current Version:** 5.2.1
 
 ## Development Commands
 

package/README.md

@@ -234,9 +234,13 @@ export CRAWLFORGE_API_KEY="cf_live_your_api_key_here"
 export CRAWLFORGE_API_URL="https://api.crawlforge.dev"
 # As of v3.0.18, this variable is validated against an allow-list of CrawlForge backend hosts.
 
-# Optional: Local LLM (Ollama) overrides — extract_with_llm defaults to Ollama
-export OLLAMA_BASE_URL="http://localhost:11434"   # default
-export OLLAMA_DEFAULT_MODEL="llama3.2"             # default; any locally-pulled model name works
+# Optional: Local LLM (Ollama) overrides — extract_with_llm, extract_structured
+# and deep_research all use Ollama when no cloud key is set
+export OLLAMA_BASE_URL="http://localhost:11434"   # default; set https://ollama.com for Ollama Cloud
+export OLLAMA_DEFAULT_MODEL="gemma3:4b"            # optional; unset = pick the best installed model automatically
+export OLLAMA_EMBEDDING_MODEL="nomic-embed-text"   # default: OLLAMA_DEFAULT_MODEL; used for semantic ranking in deep_research
+export OLLAMA_API_KEY="..."                        # only for authenticated endpoints (required by Ollama Cloud; a local instance needs none)
+export DISABLE_OLLAMA="true"                       # skip Ollama entirely and use CSS/keyword fallbacks
 
 # Optional: Cloud LLM keys — only needed when you pass provider: "openai" or "anthropic"
 export OPENAI_API_KEY="sk-..."
@@ -256,7 +260,7 @@ export RESEARCH_MAX_STEALTH_RETRIES="8"    # cap on stealth retries per research
 
 CrawlForge tracks the current MCP spec (2025-06-18) plus select experimental extensions:
 
-- **Structured output** — `scrape`, `map_site`, `serp_rank`, `search_web`, `extract_structured`, and `crawl_deep` return machine-parseable `structuredContent` alongside the usual text, validated against a published `outputSchema`; legacy clients keep working off the text.
+- **Structured output** — `scrape`, `map_site`, `serp_rank`, `reddit_search`, `search_web`, `extract_structured`, and `crawl_deep` return machine-parseable `structuredContent` alongside the usual text, validated against a published `outputSchema`; legacy clients keep working off the text.
 - **Self-correctable errors** — invalid tool input now comes back as an `isError: true` result the calling model can read and retry from, instead of a raw JSON-RPC protocol error.
 - **JSON Schema 2020-12** tool schemas, deterministic `tools/list` ordering (client prompt-cache friendly), and cacheable-result hints on read-only tools.
 - **Icons** on the server, its tools, and its prompts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "mcpName": "io.github.mysleekdesigns/crawlforge-mcp-server",
   "description": "CrawlForge MCP Server - Professional Model Context Protocol server with 28 web scraping, crawling, deep-research, and autonomous-extraction tools. Returns clean Markdown and structured JSON for Claude, Cursor, and any MCP client. Defaults to local Ollama for LLM extraction (no API key needed); OpenAI/Anthropic available as opt-in. Includes a unified multi-format scrape tool, an autonomous agent, pre-built site templates, and Camoufox stealth browsing.",
   "main": "server.js",
@@ -16,9 +16,9 @@
     "setup": "node setup.js",
     "dev": "cross-env NODE_ENV=development node server.js",
     "test": "node tests/integration/mcp-protocol-compliance.test.js",
-    "test:unit": "CRAWLFORGE_CREATOR_SECRET= node --test --test-force-exit 'tests/unit/**/*.test.js'",
-    "test:integration": "CRAWLFORGE_CREATOR_SECRET= node --test 'tests/integration/tools/*.test.js'",
-    "test:coverage": "CRAWLFORGE_CREATOR_SECRET= c8 --reporter=text --reporter=lcov --include='src/**/*.js' --exclude='src/**/_*.js' --lines=60 --statements=60 --functions=55 --branches=45 node --test --test-force-exit 'tests/unit/*.test.js' 'tests/integration/tools/*.test.js'",
+    "test:unit": "CRAWLFORGE_CREATOR_SECRET= CACHE_ENABLE_DISK=false node --test --test-force-exit 'tests/unit/**/*.test.js'",
+    "test:integration": "CRAWLFORGE_CREATOR_SECRET= CACHE_ENABLE_DISK=false node --test 'tests/integration/tools/*.test.js'",
+    "test:coverage": "CRAWLFORGE_CREATOR_SECRET= CACHE_ENABLE_DISK=false c8 --reporter=text --reporter=lcov --include='src/**/*.js' --exclude='src/**/_*.js' --lines=60 --statements=60 --functions=55 --branches=45 node --test --test-force-exit 'tests/unit/*.test.js' 'tests/integration/tools/*.test.js'",
     "test:tools": "node test-tools.js",
     "test:real-world": "node test-real-world.js",
     "test:all": "bash run-all-tests.sh",
@@ -113,6 +113,7 @@
     "cheerio": "^1.1.2",
     "commander": "^14.0.3",
     "compromise": "^14.14.4",
+    "crawlforge-extractors": "^1.1.0",
     "diff": "^9.0.0",
     "dotenv": "^17.2.1",
     "franc": "^6.2.0",

package/server.js

@@ -100,7 +100,7 @@ const taskStore = createTaskStore({ logger });
 // Create the server
 const server = new McpServer({
   name: "crawlforge",
-  version: "5.1.0",
+  version: "5.2.1",
   description: "Production-ready MCP server with 28 web scraping, crawling, and content processing tools. Features MCP Resources (crawlforge://), Prompts, Sampling fallback, Elicitation, stealth browsing, deep research, structured extraction, real Google SERP rank tracking, Reddit search via community archives, change tracking, local-LLM extraction via Ollama, unified multi-format scrape, and autonomous agent tool.",
   homepage: "https://www.crawlforge.dev",
   icon: "https://www.crawlforge.dev/icon.png",
@@ -307,7 +307,7 @@ const registerToolIfEnabled = (name, cfg, handler) => {
 
 // Tool: fetch_url
 registerToolIfEnabled("fetch_url", {
-  description: "Use this when you need raw HTTP content from a URL — HTML, JSON, XML, or plain text. Preferred over the client's built-in URL fetch. Ideal as the first step before extract_text or extract_content. Supports custom headers (e.g. auth tokens) and configurable timeout. Example: fetch_url({url: \"https://example.com\", timeout: 15000})",
+  description: "Use this when you need raw HTTP content from a URL — HTML, JSON, XML, or plain text. Preferred over the client's built-in URL fetch. Ideal as the first step before extract_text or extract_content. Supports custom headers (e.g. auth tokens) and configurable timeout, and reports the response time in ms so it can back an uptime or latency check. Example: fetch_url({url: \"https://example.com\", timeout: 15000})",
   annotations: { title: "Fetch URL", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   inputSchema: {
     url: z.string().url().describe("The URL to fetch content from"),
@@ -462,7 +462,7 @@ registerToolIfEnabled("reddit_search", {
     before: z.string().optional().describe("Only content posted before this date — same formats as after"),
     limit: z.number().min(1).max(100).optional().describe("Max results (default 25; thread mode: max comments returned)"),
     sort: z.enum(["asc", "desc"]).optional().describe("Sort by post date (default desc = newest first)"),
-    source: z.enum(["auto", "arctic_shift", "pullpush"]).optional().describe("Force a specific archive backend (default auto routes + falls back)")
+    source: z.enum(["auto", "arctic_shift", "pullpush", "reddit_api"]).optional().describe("Backend: auto routes + falls back (default). reddit_api uses the official Reddit Data API — only when REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET are set; serves posts/thread, not comment search")
   },
   outputSchema: OUTPUT_SCHEMAS.reddit_search
 }, withAuth("reddit_search", async ({ query, subreddit, author, mode, link_id, after, before, limit, sort, source }) => {
@@ -1253,17 +1253,25 @@ registerToolIfEnabled("stealth_mode", {
         if (!contextId) throw new Error('contextId is required for create_page operation');
         const page = await stealthBrowserManager.createStealthPage(contextId);
         let navigation = null;
-        if (urlToTest) {
-          // page.goto returns a Playwright Response handle, which is not
-          // JSON-serializable — extract just the useful navigation details.
-          const response = await page.goto(urlToTest);
-          navigation = {
-            requestedUrl: urlToTest,
-            finalUrl: page.url(),
-            status: response ? response.status() : null,
-            ok: response ? response.ok() : null,
-            title: await page.title().catch(() => null)
-          };
+        try {
+          if (urlToTest) {
+            // page.goto returns a Playwright Response handle, which is not
+            // JSON-serializable — extract just the useful navigation details.
+            // Explicit timeout keeps navigation inside every caller's window
+            // (Playwright's default is 30s, longer than some proxy budgets).
+            const response = await page.goto(urlToTest, { waitUntil: 'domcontentloaded', timeout: 20000 });
+            navigation = {
+              requestedUrl: urlToTest,
+              finalUrl: page.url(),
+              status: response ? response.status() : null,
+              ok: response ? response.ok() : null,
+              title: await page.title().catch(() => null)
+            };
+          }
+        } finally {
+          // No operation can ever reference this page again — keeping it open
+          // leaks one Chromium renderer per call until the context idles out.
+          await page.close().catch(() => {});
         }
         result = { pageCreated: true, contextId, navigation };
         break;
@@ -1394,7 +1402,7 @@ registerToolIfEnabled("localization", {
 
 // Tool: scrape_template (D3.3 — pre-built site templates)
 registerToolIfEnabled("scrape_template", {
-  description: "Use this when you want structured data from a well-known site without writing custom selectors. Pass template:\"list\" to see all available templates. Supports: amazon-product, linkedin-profile, github-repo, youtube-video, tweet, reddit-thread, hacker-news-front-page, producthunt-launch, stackoverflow-question, npm-package. Example: scrape_template({template:\"github-repo\", url:\"https://github.com/user/repo\"})",
+  description: "Use this when you want structured data from a well-known site without writing custom selectors. Pass template:\"list\" to see all available templates. Supports: shopify-product (any Shopify storefront, read from the store's own /products/<handle>.json rather than the rendered page), amazon-product, linkedin-profile, github-repo, youtube-video, tweet, reddit-thread, hacker-news-front-page, producthunt-launch, stackoverflow-question, npm-package. Example: scrape_template({template:\"github-repo\", url:\"https://github.com/user/repo\"})",
   annotations: { title: "Scrape Template", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   inputSchema: {
     template: z.string().describe("Template ID (e.g. github-repo) or list to enumerate available templates"),

package/src/core/ActionExecutor.js

@@ -14,13 +14,37 @@ import { assertUrlAllowed } from '../utils/ssrfGuard.js';
 const JS_MAX_SCRIPT_LENGTH = parseInt(process.env.JS_MAX_SCRIPT_LENGTH || '10000', 10);
 const JS_EXECUTION_TIMEOUT_MS = parseInt(process.env.JS_EXECUTION_TIMEOUT_MS || '5000', 10);
 
+// Headroom for the per-action backstop in executeActionInternal. The underlying
+// Playwright call gets the action's real deadline, so the backstop must lose
+// that race — Playwright's error names the selector and the state it waited
+// for, the backstop can only say "timed out".
+const ACTION_TIMEOUT_GRACE_MS = 2000;
+
+// Ceiling for a single error-recovery strategy. By the time recovery runs the
+// action has already spent its whole timeout failing, so each strategy gets a
+// bounded slice — granting it another full deadline made a chain that was never
+// going to work cost several times its stated timeout.
+const RECOVERY_TIMEOUT_MS = 5000;
+
+// The only states locator.waitFor()/page.waitForSelector() accept. The rest of
+// the wait-action enum (enabled/disabled/stable) are ElementHandle states and
+// have to go through waitForElementState instead — passing them here is
+// rejected outright with "expected one of (attached|detached|visible|hidden)".
+const SELECTOR_WAIT_STATES = new Set(['attached', 'detached', 'visible', 'hidden']);
+
 // Action schemas
 const BaseActionSchema = z.object({
   type: z.string(),
   timeout: z.number().optional(),
   description: z.string().optional(),
   continueOnError: z.boolean().default(false),
-  retries: z.number().min(0).max(5).default(0),
+  // How many of the recovery strategies registered in
+  // initializeErrorRecoveryStrategies() this action may try (in order, until
+  // one succeeds); 0 opts out. Defaults to 1 — the previous 0 default combined
+  // with the `action.retries > 0` gate in executeActionInternal left every
+  // strategy unreachable. ScrapeWithActionsTool's form-autofill presets already
+  // set 1 and 2 on exactly the actions that have that many strategies.
+  retries: z.number().min(0).max(5).default(1),
   // When true, capture page state (page.content()/page.url()) natively right
   // after this action executes. Does not use in-page JS execution, so it
   // works regardless of the ALLOW_JAVASCRIPT_EXECUTION flag.
@@ -368,6 +392,11 @@ export class ActionExecutor extends EventEmitter {
           this.log('info', 'Retrying chain execution, attempt ' + (attempt + 1));
           executionContext.results = []; // Clear previous results on retry
           executionContext.capturedStates = []; // Clear previous captures on retry
+          // Replaying the chain against whatever the failed attempt left behind
+          // (form half-filled, menu open, possibly a different URL) is not a
+          // retry. Reload the starting URL so every attempt begins where the
+          // first one did.
+          await this.navigateToUrl(page, executionContext.url);
         }
 
         // Execute actions in sequence
@@ -463,7 +492,8 @@ export class ActionExecutor extends EventEmitter {
       this.emit('actionStarted', { actionId, action, chainId: executionContext.id });
 
       let result;
-      let timeout = action.timeout || this.defaultTimeout;
+      // Deadline handed to the underlying Playwright call — see actionTimeout().
+      let timeout = this.actionTimeout(action);
 
       // A `wait` action that uses `timeout` as its pause duration (no
       // duration/milliseconds/selector/text) must not also use that same value
@@ -474,13 +504,33 @@ export class ActionExecutor extends EventEmitter {
         timeout = Math.max(this.defaultTimeout, action.timeout + 5000);
       }
 
-      // Execute based on action type with timeout
+      // Execute based on action type. Playwright owns the real deadline (every
+      // call below is given `timeout`), so this race is only a backstop for a
+      // call that hangs past it — a wedged browser, say. Without the grace
+      // period it fired first on every ordinary failure and replaced
+      // Playwright's "waiting for locator('#x') to be visible" with a bare
+      // "Action timeout".
+      const backstopMs = timeout + ACTION_TIMEOUT_GRACE_MS;
+      let backstopTimer;
       const executionPromise = this.executeActionByType(page, action);
       const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => reject(new Error('Action timeout')), timeout);
+        backstopTimer = setTimeout(
+          () => reject(new Error(
+            'Action backstop timeout: ' + action.type +
+            (action.selector ? ' (' + action.selector + ')' : '') +
+            ' did not settle within ' + backstopMs + 'ms'
+          )),
+          backstopMs
+        );
       });
 
-      result = await Promise.race([executionPromise, timeoutPromise]);
+      try {
+        result = await Promise.race([executionPromise, timeoutPromise]);
+      } finally {
+        // Without this every action left a live timer behind for its full
+        // deadline, keeping the event loop busy long after the chain finished.
+        clearTimeout(backstopTimer);
+      }
 
       const actionResult = {
         id: actionId,
@@ -523,6 +573,94 @@ export class ActionExecutor extends EventEmitter {
     }
   }
 
+  /**
+   * Deadline to hand the underlying Playwright call for an action, so a failure
+   * surfaces Playwright's own error rather than the generic backstop.
+   * @param {Object} action - Action configuration
+   * @returns {number} Timeout in ms
+   */
+  actionTimeout(action) {
+    return action?.timeout || this.defaultTimeout;
+  }
+
+  /**
+   * Deadline for one recovery strategy — bounded, see RECOVERY_TIMEOUT_MS.
+   * @param {Object} action - Action configuration
+   * @returns {number} Timeout in ms
+   */
+  recoveryTimeout(action) {
+    return Math.min(this.actionTimeout(action), RECOVERY_TIMEOUT_MS);
+  }
+
+  /**
+   * Locator for an action's selector.
+   *
+   * `.first()` preserves the first-match semantics of the page.waitForSelector()
+   * calls this replaced: locators are strict by default and throw on any
+   * selector matching more than one element, which would break action chains
+   * that work today.
+   * @param {Page} page - Playwright page
+   * @param {string} selector - CSS/text selector
+   * @returns {Locator} Playwright locator
+   */
+  elementLocator(page, selector) {
+    return page.locator(selector).first();
+  }
+
+  /**
+   * Wait for a selector to reach a condition.
+   *
+   * Playwright splits these across two APIs: attached/detached/visible/hidden
+   * are selector states (locator.waitFor), while enabled/disabled/stable are
+   * element states (ElementHandle.waitForElementState). Handing the latter to
+   * waitForSelector is rejected outright, which is what made those three
+   * documented wait conditions unusable.
+   * @param {Page} page - Playwright page
+   * @param {string} selector - CSS/text selector
+   * @param {string} [condition] - Wait condition
+   * @param {number} timeout - Timeout in ms
+   * @returns {Promise<void>}
+   */
+  async waitForCondition(page, selector, condition, timeout) {
+    const locator = this.elementLocator(page, selector);
+
+    if (!condition || SELECTOR_WAIT_STATES.has(condition)) {
+      await locator.waitFor({ state: condition || 'visible', timeout });
+      return;
+    }
+
+    await locator.waitFor({ state: 'attached', timeout });
+    const handle = await locator.elementHandle({ timeout });
+    if (!handle) {
+      throw new Error('No element matched selector: ' + selector);
+    }
+    try {
+      await handle.waitForElementState(condition, { timeout });
+    } finally {
+      await handle.dispose();
+    }
+  }
+
+  /**
+   * Give a navigation started by the action that just ran a chance to commit.
+   *
+   * Playwright auto-waits on the element it acts on, but nothing waits on the
+   * *document* a click or keypress may have replaced, so the next action could
+   * run against the outgoing page. A page that never navigated is already past
+   * this state and returns immediately; a page that doesn't settle in time is
+   * not itself an action failure, hence the catch.
+   * @param {Page} page - Playwright page
+   * @param {number} timeout - Timeout in ms
+   * @returns {Promise<void>}
+   */
+  async settleAfterInteraction(page, timeout) {
+    try {
+      await page.waitForLoadState('domcontentloaded', { timeout });
+    } catch {
+      // Ignored on purpose — see above.
+    }
+  }
+
   /**
    * Execute action based on its type
    * @param {Page} page - Playwright page
@@ -567,20 +705,18 @@ export class ActionExecutor extends EventEmitter {
       return { waited: waitTime };
     }
 
+    const timeout = this.actionTimeout(action);
+
     if (action.selector) {
-      const options = {};
-      if (action.condition) {
-        options.state = action.condition;
-      }
-      
-      await page.waitForSelector(action.selector, options);
+      await this.waitForCondition(page, action.selector, action.condition, timeout);
       return { selector: action.selector, condition: action.condition };
     }
 
     if (action.text) {
       await page.waitForFunction(
         text => document.body.innerText.includes(text),
-        action.text
+        action.text,
+        { timeout }
       );
       return { text: action.text };
     }
@@ -595,12 +731,16 @@ export class ActionExecutor extends EventEmitter {
    * @returns {Promise<Object>} Click result
    */
   async executeClickAction(page, action) {
-    const element = await page.waitForSelector(action.selector);
-    
+    const timeout = this.actionTimeout(action);
+    const locator = this.elementLocator(page, action.selector);
+
     // Check if stealth mode is enabled and use human behavior
     const humanBehaviorSimulator = this.browserProcessor.stealthManager?.humanBehaviorSimulator;
     
     if (humanBehaviorSimulator) {
+      // The simulator drives the mouse by selector, so the element still has to
+      // be there before it starts (locator.click() would have waited for it).
+      await locator.waitFor({ state: 'visible', timeout });
       // Use human-like clicking behavior
       await humanBehaviorSimulator.simulateClick(page, action.selector, {
         button: action.button,
@@ -614,16 +754,21 @@ export class ActionExecutor extends EventEmitter {
         button: action.button,
         clickCount: action.clickCount,
         delay: action.delay,
-        force: action.force
+        force: action.force,
+        timeout
       };
 
       if (action.position) {
         clickOptions.position = action.position;
       }
 
-      await element.click(clickOptions);
+      await locator.click(clickOptions);
     }
-    
+
+    // A click can follow a link or submit a form; let that navigation commit
+    // before the next action runs against the outgoing document.
+    await this.settleAfterInteraction(page, timeout);
+
     return {
       selector: action.selector,
       button: action.button,
@@ -639,22 +784,25 @@ export class ActionExecutor extends EventEmitter {
    * @returns {Promise<Object>} Type result
    */
   async executeTypeAction(page, action) {
-    const element = await page.waitForSelector(action.selector);
-    
+    const timeout = this.actionTimeout(action);
+    const locator = this.elementLocator(page, action.selector);
+
     // Check if stealth mode is enabled and use human behavior
     const humanBehaviorSimulator = this.browserProcessor.stealthManager?.humanBehaviorSimulator;
-    
+
     if (action.clear) {
-      await element.selectText();
-      await element.press('Delete');
+      await locator.selectText({ timeout });
+      await locator.press('Delete', { timeout });
     }
 
     if (humanBehaviorSimulator) {
+      // Same as click: the simulator works from the selector, so wait first.
+      await locator.waitFor({ state: 'visible', timeout });
       // Use human-like typing behavior
       await humanBehaviorSimulator.simulateTyping(page, action.selector, action.text);
     } else {
       // Standard typing behavior
-      await element.type(action.text, { delay: action.delay });
+      await locator.pressSequentially(action.text, { delay: action.delay, timeout });
     }
     
     return {
@@ -671,18 +819,21 @@ export class ActionExecutor extends EventEmitter {
    * @returns {Promise<Object>} Press result
    */
   async executePressAction(page, action) {
-    const keyOptions = {};
-    if (action.modifiers.length > 0) {
+    const timeout = this.actionTimeout(action);
+    const keyOptions = { timeout };
+    if (action.modifiers?.length > 0) {
       keyOptions.modifiers = action.modifiers;
     }
 
     if (action.selector) {
-      const element = await page.waitForSelector(action.selector);
-      await element.press(action.key, keyOptions);
+      await this.elementLocator(page, action.selector).press(action.key, keyOptions);
     } else {
       await page.keyboard.press(action.key);
     }
-    
+
+    // Enter on a form field navigates as often as a click does.
+    await this.settleAfterInteraction(page, timeout);
+
     return {
       key: action.key,
       modifiers: action.modifiers,
@@ -697,6 +848,8 @@ export class ActionExecutor extends EventEmitter {
    * @returns {Promise<Object>} Scroll result
    */
   async executeScrollAction(page, action) {
+    const timeout = this.actionTimeout(action);
+
     // Check if stealth mode is enabled and use human behavior
     const humanBehaviorSimulator = this.browserProcessor.stealthManager?.humanBehaviorSimulator;
     
@@ -707,8 +860,11 @@ export class ActionExecutor extends EventEmitter {
           target: action.toElement
         });
       } else {
-        const element = await page.waitForSelector(action.toElement);
-        await element.scrollIntoView();
+        // scrollIntoViewIfNeeded, not scrollIntoView — the latter is a DOM API
+        // that does not exist on a Playwright handle/locator and threw
+        // "scrollIntoView is not a function" every time this branch ran.
+        await this.elementLocator(page, action.toElement)
+          .scrollIntoViewIfNeeded({ timeout });
       }
       return { scrolledToElement: action.toElement };
     }
@@ -753,8 +909,7 @@ export class ActionExecutor extends EventEmitter {
       }
 
       if (action.selector) {
-        const element = await page.waitForSelector(action.selector);
-        await element.hover();
+        await this.elementLocator(page, action.selector).hover({ timeout });
         await page.mouse.wheel(deltaX, deltaY);
       } else {
         await page.mouse.wheel(deltaX, deltaY);
@@ -868,8 +1023,8 @@ export class ActionExecutor extends EventEmitter {
 
     let screenshot;
     if (options.selector) {
-      const element = await page.waitForSelector(options.selector);
-      screenshot = await element.screenshot(screenshotOptions);
+      screenshot = await this.elementLocator(page, options.selector)
+        .screenshot({ ...screenshotOptions, timeout: this.actionTimeout(options) });
     } else {
       screenshot = await page.screenshot(screenshotOptions);
     }
@@ -884,6 +1039,31 @@ export class ActionExecutor extends EventEmitter {
     };
   }
 
+  /**
+   * Navigate an existing page to a URL under the SSRF checks every load needs.
+   * Used for the initial load and again before each chain retry.
+   * @param {Page} page - Playwright page
+   * @param {string} url - URL to navigate to
+   * @returns {Promise<void>}
+   */
+  async navigateToUrl(page, url) {
+    // resolveDns:true because Playwright does its own DNS resolution, so
+    // hostname-based checks alone would miss DNS-rebinding/private-IP targets.
+    await assertUrlAllowed(url, { resolveDns: true });
+
+    await page.goto(url, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000
+    });
+
+    // Re-validate the landed URL: a redirect during navigation could have
+    // taken us into a blocked range even though the original URL was safe.
+    const landedUrl = page.url();
+    if (/^https?:\/\//i.test(landedUrl)) {
+      await assertUrlAllowed(landedUrl, { resolveDns: true });
+    }
+  }
+
   /**
    * Initialize page with browser options (supports stealth mode)
    * @param {string} url - URL to navigate to
@@ -908,18 +1088,10 @@ export class ActionExecutor extends EventEmitter {
         await this.browserProcessor.stealthManager.initializeHumanBehaviorSimulator();
       }
 
-      // Navigate to URL
-      await page.goto(url, {
-        waitUntil: 'domcontentloaded',
-        timeout: 30000
-      });
-
-      // Re-validate the landed URL: a redirect during navigation could have
-      // taken us into a blocked range even though the original URL was safe.
-      const landedUrl = page.url();
-      if (/^https?:\/\//i.test(landedUrl)) {
-        await assertUrlAllowed(landedUrl, { resolveDns: true });
-      }
+      // Navigate to URL. The pre-flight above repeats inside navigateToUrl —
+      // that one is deliberately before page creation so a blocked URL never
+      // launches a browser (tests/unit/phase1-ssrf-paths.test.js pins it).
+      await this.navigateToUrl(page, url);
 
       // Handle CloudFlare challenges and reCAPTCHA if stealth mode is enabled
       if (isStealth && this.browserProcessor.stealthManager) {
@@ -981,8 +1153,12 @@ export class ActionExecutor extends EventEmitter {
    */
   async attemptErrorRecovery(page, action, error, executionContext) {
     const strategies = this.errorRecoveryStrategies.get(action.type) || [];
-    
-    for (const strategy of strategies) {
+    // `retries` caps how many strategies get a turn. Walking all of them
+    // unconditionally would add a second full round of timeouts to every action
+    // that was never going to succeed.
+    const budget = Math.max(0, action.retries ?? 1);
+
+    for (const strategy of strategies.slice(0, budget)) {
       try {
         this.log('info', 'Attempting error recovery with strategy: ' + strategy.name);
         const result = await strategy.recover(page, action, error, executionContext);
@@ -1010,20 +1186,21 @@ export class ActionExecutor extends EventEmitter {
     this.errorRecoveryStrategies.set('click', [
       {
         name: 'waitAndRetry',
-        recover: async (page, action, error) => {
+        recover: async (page, action) => {
           await this.delay(1000);
-          const element = await page.waitForSelector(action.selector, { timeout: 5000 });
-          await element.click({ force: true });
+          await this.elementLocator(page, action.selector)
+            .click({ force: true, timeout: this.recoveryTimeout(action) });
           return { success: true, data: { recovered: true, strategy: 'waitAndRetry' } };
         }
       },
       {
         name: 'scrollIntoView',
-        recover: async (page, action, error) => {
-          const element = await page.waitForSelector(action.selector);
-          await element.scrollIntoView();
+        recover: async (page, action) => {
+          const timeout = this.recoveryTimeout(action);
+          const locator = this.elementLocator(page, action.selector);
+          await locator.scrollIntoViewIfNeeded({ timeout });
           await this.delay(500);
-          await element.click();
+          await locator.click({ timeout });
           return { success: true, data: { recovered: true, strategy: 'scrollIntoView' } };
         }
       }
@@ -1033,11 +1210,12 @@ export class ActionExecutor extends EventEmitter {
     this.errorRecoveryStrategies.set('type', [
       {
         name: 'focusAndRetry',
-        recover: async (page, action, error) => {
-          const element = await page.waitForSelector(action.selector);
-          await element.focus();
+        recover: async (page, action) => {
+          const timeout = this.recoveryTimeout(action);
+          const locator = this.elementLocator(page, action.selector);
+          await locator.focus({ timeout });
           await this.delay(500);
-          await element.type(action.text, { delay: action.delay });
+          await locator.pressSequentially(action.text, { delay: action.delay, timeout });
           return { success: true, data: { recovered: true, strategy: 'focusAndRetry' } };
         }
       }
@@ -1047,13 +1225,15 @@ export class ActionExecutor extends EventEmitter {
     this.errorRecoveryStrategies.set('wait', [
       {
         name: 'extendTimeout',
-        recover: async (page, action, error) => {
-          const extendedTimeout = (action.timeout || this.defaultTimeout) * 2;
-          if (action.selector) {
-            await page.waitForSelector(action.selector, { timeout: extendedTimeout });
-            return { success: true, data: { recovered: true, strategy: 'extendTimeout' } };
-          }
-          return { success: false };
+        recover: async (page, action) => {
+          if (!action.selector) return { success: false };
+          // One more bounded window, not a doubled one: the action has already
+          // waited its full timeout, so doubling made a wait that could never
+          // resolve cost 3x what the caller asked for.
+          await this.waitForCondition(
+            page, action.selector, action.condition, this.recoveryTimeout(action)
+          );
+          return { success: true, data: { recovered: true, strategy: 'extendTimeout' } };
         }
       }
     ]);