@jshookmcp/jshook 0.1.6 → 0.1.8

package/dist/server/domains/browser/definitions.tools.behavior.js

@@ -6,7 +6,7 @@ export const behaviorTools = [
             '- Non-linear speed (ease-in-out)\n' +
             '- Configurable jitter/noise\n' +
             '- Viewport-clamped trajectory\n\n' +
-            'Use this before page_click for anti-bot bypass (e.g. Cloudflare, Turnstile).\n\n' +
+            'Use this before page_click for anti-bot bypass on browser-check or widget challenges.\n\n' +
             'Example:\n' +
             '  human_mouse({ toX: 500, toY: 300, durationMs: 800 })',
         inputSchema: {
@@ -74,28 +74,36 @@ export const behaviorTools = [
     {
         name: 'captcha_vision_solve',
         description: 'Attempt to solve a CAPTCHA using an external solving service or AI vision.\n\n' +
-            'Supports multiple providers through a provider-agnostic interface:\n' +
-            '- `2captcha` / `anticaptcha` / `capsolver` — external solving services\n' +
-            '- `manual` — wait for user to solve manually (fallback)\n\n' +
-            'Automatically detects CAPTCHA type (image, reCAPTCHA, hCaptcha) if typeHint is not provided.\n\n' +
+            'Public contract:\n' +
+            '- `mode: "external_service"` routes to the configured solver backend\n' +
+            '- `mode: "manual"` waits for the user to solve manually\n\n' +
+            'Automatically detects the challenge class (`image` or `widget`) if `challengeType` is omitted.\n\n' +
             'Example:\n' +
-            '  captcha_vision_solve({ provider: "2captcha", apiKey: "..." })',
+            '  captcha_vision_solve({ mode: "external_service", apiKey: "..." })',
         inputSchema: {
             type: 'object',
             properties: {
+                mode: {
+                    type: 'string',
+                    enum: ['external_service', 'manual'],
+                    description: 'Solver mode (default: from config or "manual")',
+                },
                 provider: {
                     type: 'string',
-                    enum: ['2captcha', 'anticaptcha', 'capsolver', 'manual'],
-                    description: 'Solving service provider (default: from config or "manual")',
+                    description: 'Deprecated legacy external-service override; avoid in new callers',
                 },
-                apiKey: { type: 'string', description: 'Provider API key (default: from CAPTCHA_API_KEY env)' },
-                typeHint: {
+                apiKey: { type: 'string', description: 'External solver API key (default: from CAPTCHA_API_KEY env)' },
+                challengeType: {
                     type: 'string',
-                    enum: ['image', 'recaptcha_v2', 'recaptcha_v3', 'hcaptcha', 'funcaptcha', 'turnstile', 'auto'],
-                    description: 'CAPTCHA type hint (default: auto-detect)',
+                    enum: ['image', 'widget', 'browser_check', 'auto'],
+                    description: 'Generic challenge type hint (default: auto-detect)',
                     default: 'auto',
                 },
-                siteKey: { type: 'string', description: 'Site key for reCAPTCHA/hCaptcha/Turnstile (auto-extracted if omitted)' },
+                typeHint: {
+                    type: 'string',
+                    description: 'Deprecated legacy alias for challengeType; avoid in new callers',
+                },
+                siteKey: { type: 'string', description: 'Widget site key (auto-extracted if omitted)' },
                 pageUrl: { type: 'string', description: 'Page URL for context (auto-detected if omitted)' },
                 timeoutMs: { type: 'number', description: 'Max solve time in ms (default: 180000)', default: 180000 },
                 maxRetries: { type: 'integer', description: 'Max retry attempts (default: 2)', default: 2 },
@@ -103,27 +111,31 @@ export const behaviorTools = [
         },
     },
     {
-        name: 'turnstile_solve',
-        description: 'Solve a Cloudflare Turnstile challenge specifically.\n\n' +
+        name: 'widget_challenge_solve',
+        description: 'Solve an embedded widget challenge.\n\n' +
             'Strategy:\n' +
-            '1. Detect Turnstile widget and extract siteKey\n' +
-            '2. Send to solving service (or hook window.cf to extract token)\n' +
-            '3. Inject solved token back into the page\n' +
+            '1. Detect the widget and extract siteKey\n' +
+            '2. Send to the configured external solver service (or hook the page callback to extract token)\n' +
+            '3. Inject the solved token back into the page\n' +
             '4. Trigger callback to proceed\n\n' +
-            'Requires either an external solver API key or uses the built-in hook approach.\n\n' +
+            'Requires either external solver credentials or uses the built-in hook approach.\n\n' +
             'Example:\n' +
-            '  turnstile_solve({ provider: "capsolver" })',
+            '  widget_challenge_solve({ mode: "external_service" })',
         inputSchema: {
             type: 'object',
             properties: {
-                siteKey: { type: 'string', description: 'Turnstile site key (auto-detected if omitted)' },
+                siteKey: { type: 'string', description: 'Widget site key (auto-detected if omitted)' },
                 pageUrl: { type: 'string', description: 'Page URL (auto-detected if omitted)' },
+                mode: {
+                    type: 'string',
+                    enum: ['external_service', 'hook', 'manual'],
+                    description: 'Solving mode (default: from config or "manual")',
+                },
                 provider: {
                     type: 'string',
-                    enum: ['2captcha', 'anticaptcha', 'capsolver', 'hook', 'manual'],
-                    description: 'Solving method (default: from config or "manual")',
+                    description: 'Deprecated legacy external-service override; avoid in new callers',
                 },
-                apiKey: { type: 'string', description: 'Provider API key' },
+                apiKey: { type: 'string', description: 'External solver API key' },
                 timeoutMs: { type: 'number', description: 'Max solve time in ms (default: 120000)', default: 120000 },
                 injectToken: { type: 'boolean', description: 'Auto-inject solved token into page (default: true)', default: true },
             },

package/dist/server/domains/browser/definitions.tools.page-core.js

@@ -1,22 +1,22 @@
 export const browserPageCoreTools = [
     {
         name: 'page_navigate',
-        description: `Navigate to a URL
-
-Features:
-- Automatic CAPTCHA detection
-- Optional network monitoring (set enableNetworkMonitoring=true to auto-enable)
-- Waits for page load based on waitUntil strategy
-
-Network Monitoring:
-If you want to capture network requests, you have two options:
-1. Call network_enable before page_navigate (recommended for full control)
-2. Set enableNetworkMonitoring=true in page_navigate (convenient for quick capture)
-
-Example with network monitoring:
-page_navigate(url="https:
--> Network monitoring auto-enabled
--> Page loads
+        description: `Navigate to a URL
+
+Features:
+- Automatic CAPTCHA detection
+- Optional network monitoring (set enableNetworkMonitoring=true to auto-enable)
+- Waits for page load based on waitUntil strategy
+
+Network Monitoring:
+If you want to capture network requests, you have two options:
+1. Call network_enable before page_navigate (recommended for full control)
+2. Set enableNetworkMonitoring=true in page_navigate (convenient for quick capture)
+
+Example with network monitoring:
+page_navigate(url="https:
+-> Network monitoring auto-enabled
+-> Page loads
 -> Use network_get_requests to see captured requests`,
         inputSchema: {
             type: 'object',
@@ -109,17 +109,17 @@ page_navigate(url="https:
     },
     {
         name: 'dom_get_structure',
-        description: `Get page DOM structure (for AI to understand page layout).
-
-IMPORTANT: Large DOM structures (>50KB) automatically return summary + detailId.
-
-Best Practices:
-1. Use maxDepth=2 for initial exploration (faster, smaller)
-2. Use maxDepth=3 only when needed (may be large)
-3. Set includeText=false to reduce size if text not needed
-
-Example:
-dom_get_structure(maxDepth=2, includeText=false)
+        description: `Get page DOM structure (for AI to understand page layout).
+
+IMPORTANT: Large DOM structures (>50KB) automatically return summary + detailId.
+
+Best Practices:
+1. Use maxDepth=2 for initial exploration (faster, smaller)
+2. Use maxDepth=3 only when needed (may be large)
+3. Set includeText=false to reduce size if text not needed
+
+Example:
+dom_get_structure(maxDepth=2, includeText=false)
 -> Returns compact structure without text content`,
         inputSchema: {
             type: 'object',
@@ -276,19 +276,19 @@ dom_get_structure(maxDepth=2, includeText=false)
     },
     {
         name: 'page_evaluate',
-        description: `Execute JavaScript code in page context and get result.
-
-IMPORTANT: Large results (>50KB) automatically return summary + detailId to prevent context overflow.
-Use get_detailed_data(detailId) to retrieve full data if needed.
-
-Best Practices:
--  Query specific properties: { hasAcrawler: !!window.byted_acrawler }
--  Return only needed data: Object.keys(window.byted_acrawler)
--  Avoid returning entire objects: window (too large!)
-
-Example:
-page_evaluate("({ keys: Object.keys(window.byted_acrawler), type: typeof window.byted_acrawler })")
--> Returns small summary
+        description: `Execute JavaScript code in page context and get result.
+
+IMPORTANT: Large results (>50KB) automatically return summary + detailId to prevent context overflow.
+Use get_detailed_data(detailId) to retrieve full data if needed.
+
+Best Practices:
+-  Query specific properties: { hasAcrawler: !!window.byted_acrawler }
+-  Return only needed data: Object.keys(window.byted_acrawler)
+-  Avoid returning entire objects: window (too large!)
+
+Example:
+page_evaluate("({ keys: Object.keys(window.byted_acrawler), type: typeof window.byted_acrawler })")
+-> Returns small summary
 -> If you need full object, use the returned detailId`,
         inputSchema: {
             type: 'object',
@@ -369,19 +369,19 @@ page_evaluate("({ keys: Object.keys(window.byted_acrawler), type: typeof window.
     },
     {
         name: 'get_script_source',
-        description: `Get source code of a specific script.
-
-IMPORTANT: Large scripts (>50KB) automatically return summary + detailId.
-Use preview mode first to check script size before fetching full source.
-
-Best Practices:
-1. Use preview=true first to see script overview
-2. If script is large, use detailId to get full source
-3. Or use startLine/endLine to get specific sections
-
-Example:
-get_script_source(scriptId="abc", preview=true)
--> Returns: { lines: 5000, size: "500KB", preview: "...", detailId: "..." }
+        description: `Get source code of a specific script.
+
+IMPORTANT: Large scripts (>50KB) automatically return summary + detailId.
+Use preview mode first to check script size before fetching full source.
+
+Best Practices:
+1. Use preview=true first to see script overview
+2. If script is large, use detailId to get full source
+3. Or use startLine/endLine to get specific sections
+
+Example:
+get_script_source(scriptId="abc", preview=true)
+-> Returns: { lines: 5000, size: "500KB", preview: "...", detailId: "..." }
 -> Then: get_detailed_data(detailId) to get full source`,
         inputSchema: {
             type: 'object',

package/dist/server/domains/browser/definitions.tools.runtime.js

@@ -1,14 +1,14 @@
 export const browserRuntimeTools = [
     {
         name: 'get_detailed_data',
-        description: ` Retrieve detailed data using detailId token.
-
-When tools return large data, they provide a detailId instead of full data to prevent context overflow.
-Use this tool to retrieve the full data or specific parts.
-
-Examples:
-- get_detailed_data("detail_abc123") -> Get full data
-- get_detailed_data("detail_abc123", path="frontierSign") -> Get specific property
+        description: ` Retrieve detailed data using detailId token.
+
+When tools return large data, they provide a detailId instead of full data to prevent context overflow.
+Use this tool to retrieve the full data or specific parts.
+
+Examples:
+- get_detailed_data("detail_abc123") -> Get full data
+- get_detailed_data("detail_abc123", path="frontierSign") -> Get specific property
 - get_detailed_data("detail_abc123", path="methods.0") -> Get first method`,
         inputSchema: {
             type: 'object',
@@ -27,18 +27,18 @@ Examples:
     },
     {
         name: 'browser_launch',
-        description: `Launch browser instance.
-
-Drivers:
-- chrome (default): rebrowser-puppeteer-core, Chromium-based, full CDP support (debugger, network, stealth scripts, etc.)
-- camoufox: Firefox-based anti-detect browser, C++ engine-level fingerprint spoofing.
-  Requires binaries first: npx camoufox-js fetch
-  Note: CDP tools (debugger, network monitor, etc.) are not available in camoufox mode.
-
-Modes:
-- launch (default): launch a local browser instance
-- connect: reuse an existing browser instance
-  - chrome: connect via browserURL (http://host:port) or wsEndpoint
+        description: `Launch browser instance.
+
+Drivers:
+- chrome (default): rebrowser-puppeteer-core, Chromium-based, full CDP support (debugger, network, stealth scripts, etc.)
+- camoufox: Firefox-based anti-detect browser, C++ engine-level fingerprint spoofing.
+  Requires binaries first: npx camoufox-js fetch
+  Note: CDP tools (debugger, network monitor, etc.) are not available in camoufox mode.
+
+Modes:
+- launch (default): launch a local browser instance
+- connect: reuse an existing browser instance
+  - chrome: connect via browserURL (http://host:port) or wsEndpoint
   - camoufox: connect via wsEndpoint from camoufox_server_launch`,
         inputSchema: {
             type: 'object',
@@ -79,16 +79,16 @@ Modes:
     },
     {
         name: 'camoufox_server_launch',
-        description: `Launch a Camoufox WebSocket server for multi-process / remote connections.
-
-Use this when you need concurrent browser instances or want to manage the browser lifecycle separately from the automation client.
-
-Steps:
-1. Call camoufox_server_launch → get wsEndpoint
-2. Call browser_launch(driver="camoufox", mode="connect", wsEndpoint=<endpoint>) from one or more sessions
-3. Use page_navigate and other tools normally
-4. Call camoufox_server_close when done
-
+        description: `Launch a Camoufox WebSocket server for multi-process / remote connections.
+
+Use this when you need concurrent browser instances or want to manage the browser lifecycle separately from the automation client.
+
+Steps:
+1. Call camoufox_server_launch → get wsEndpoint
+2. Call browser_launch(driver="camoufox", mode="connect", wsEndpoint=<endpoint>) from one or more sessions
+3. Use page_navigate and other tools normally
+4. Call camoufox_server_close when done
+
 Requires binaries: npx camoufox-js fetch`,
         inputSchema: {
             type: 'object',
@@ -133,16 +133,16 @@ Requires binaries: npx camoufox-js fetch`,
     },
     {
         name: 'browser_attach',
-        description: `Attach to an existing browser instance via Chrome DevTools Protocol (CDP).
-
-Use this when a browser is already running with remote debugging enabled.
-Supports both browserURL (http://host:port) and WebSocket endpoint (ws://...).
-
-Example:
-- browser_attach(browserURL="http://127.0.0.1:9222")
-- browser_attach(wsEndpoint="ws://127.0.0.1:9222/devtools/browser/xxx")
-- browser_attach(browserURL="http://127.0.0.1:9222", pageIndex=0)
-
+        description: `Attach to an existing browser instance via Chrome DevTools Protocol (CDP).
+
+Use this when a browser is already running with remote debugging enabled.
+Supports both browserURL (http://host:port) and WebSocket endpoint (ws://...).
+
+Example:
+- browser_attach(browserURL="http://127.0.0.1:9222")
+- browser_attach(wsEndpoint="ws://127.0.0.1:9222/devtools/browser/xxx")
+- browser_attach(browserURL="http://127.0.0.1:9222", pageIndex=0)
+
 After attaching, use page_navigate / page_screenshot / debugger_enable normally.`,
         inputSchema: {
             type: 'object',

package/dist/server/domains/browser/definitions.tools.security.js

@@ -1,32 +1,33 @@
 export const browserSecurityStateTools = [
     {
         name: 'captcha_detect',
-        description: `Detect CAPTCHA on the current page using AI vision analysis.
-
-Detection process:
-1. Takes a screenshot and analyzes it with AI (Vision LLM)
-2. Applies rule-based detection as fallback if AI unavailable
-3. Returns detection result with confidence score
-
-Supported CAPTCHA types:
-- Slider CAPTCHA: drag-to-verify style challenges
-- Image CAPTCHA: select-images challenges
-- reCAPTCHA / hCaptcha
-- Cloudflare Challenge
-- Custom CAPTCHA implementations
-
-Response fields:
-- detected: whether CAPTCHA was found
-- type: CAPTCHA type identifier
-- vendor: vendor name if identified
-- confidence: detection confidence (0-100)
-- reasoning: AI analysis explanation
-- screenshot: base64 screenshot (if MCP cannot view images, use external AI)
-- suggestions: recommended next steps
-
-Note:
-When the MCP LLM cannot access Vision API directly, the screenshot is provided as base64.
-Use an external AI (GPT-4o, Claude 3) to analyze the screenshot.`,
+        description: `Detect CAPTCHA on the current page using AI vision analysis.
+
+Detection process:
+1. Takes a screenshot and analyzes it with AI (Vision LLM)
+2. Applies rule-based detection as fallback if AI unavailable
+3. Returns detection result with confidence score
+
+Supported CAPTCHA types:
+- Slider CAPTCHA: drag-to-verify style challenges
+- Image CAPTCHA: select-images challenges
+- Widget CAPTCHA: embedded checkbox or iframe-based challenges
+- Browser Check: interstitial or automatic integrity checks
+- Custom CAPTCHA implementations
+
+Response fields:
+- detected: whether CAPTCHA was found
+- type: CAPTCHA type identifier
+- providerHint: broad provider category if identified
+- confidence: detection confidence (0-100)
+- reasoning: AI analysis explanation
+- screenshotPath: saved screenshot path when a vision-capable model is unavailable
+- suggestions: recommended next steps
+
+Note:
+When the configured MCP model cannot access vision directly, the detector saves a screenshot
+to disk and returns screenshotPath together with prompt guidance in the reasoning field.
+Use an external AI (GPT-4o, Claude 3) to analyze the saved screenshot if needed.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -34,14 +35,16 @@ Use an external AI (GPT-4o, Claude 3) to analyze the screenshot.`,
     },
     {
         name: 'captcha_wait',
-        description: `Wait for the user to manually solve a CAPTCHA.
-
-Steps:
-1. CAPTCHA is detected on the page
-2. Browser switches to headed (visible) mode
-3. User solves the CAPTCHA manually
-4. Script resumes automatically after detection
-
+        description: `Wait for the user to manually solve a CAPTCHA.
+
+Steps:
+1. CAPTCHA is detected on the page
+2. This tool polls the current page until the CAPTCHA is no longer detected
+3. User solves the CAPTCHA manually in the active browser/page
+4. Script resumes automatically after detection
+
+Note: this tool does not switch browser modes on its own.
+
 Timeout: default 300000ms (5 minutes)`,
         inputSchema: {
             type: 'object',
@@ -56,11 +59,11 @@ Timeout: default 300000ms (5 minutes)`,
     },
     {
         name: 'captcha_config',
-        description: `Configure CAPTCHA detection behavior.
-
-Parameters:
-- autoDetectCaptcha: auto-detect CAPTCHA after page_navigate (default: true)
-- autoSwitchHeadless: auto-switch to headed mode when CAPTCHA detected (default: true)
+        description: `Configure CAPTCHA detection behavior.
+
+Parameters:
+- autoDetectCaptcha: enable CAPTCHA auto-handling for browser-mode integrations that use these settings
+- autoSwitchHeadless: allow supported integrations to switch to headed mode when CAPTCHA is detected
 - captchaTimeout: timeout for waiting user to solve CAPTCHA in ms (default: 300000)`,
         inputSchema: {
             type: 'object',
@@ -82,21 +85,21 @@ Parameters:
     },
     {
         name: 'stealth_inject',
-        description: `Inject modern stealth scripts to bypass bot detection.
-
-Anti-detection patches:
-1. Hide navigator.webdriver flag
-2. Inject window.chrome object
-3. Restore navigator.plugins
-4. Fix Permissions API behavior
-5. Patch Canvas fingerprinting
-6. Patch WebGL fingerprinting
-7. Restore hardware concurrency
-8. Fix Battery API responses
-9. Fix MediaDevices enumeration
-10. Fix Notification API
-
-Compatible with undetected-chromedriver, puppeteer-extra-plugin-stealth, playwright-stealth.
+        description: `Inject modern stealth scripts to bypass bot detection.
+
+Anti-detection patches:
+1. Hide navigator.webdriver flag
+2. Inject window.chrome object
+3. Restore navigator.plugins
+4. Fix Permissions API behavior
+5. Patch Canvas fingerprinting
+6. Patch WebGL fingerprinting
+7. Restore hardware concurrency
+8. Fix Battery API responses
+9. Fix MediaDevices enumeration
+10. Fix Notification API
+
+Compatible with undetected-chromedriver, puppeteer-extra-plugin-stealth, playwright-stealth.
 Call after browser_launch for best results.`,
         inputSchema: {
             type: 'object',
@@ -105,10 +108,10 @@ Call after browser_launch for best results.`,
     },
     {
         name: 'stealth_set_user_agent',
-        description: `Set a realistic User-Agent and browser fingerprint for the target platform.
-
-Updates navigator.userAgent, navigator.platform, navigator.vendor,
-navigator.hardwareConcurrency, and navigator.deviceMemory consistently
+        description: `Set a realistic User-Agent and browser fingerprint for the target platform.
+
+Updates navigator.userAgent, navigator.platform, navigator.vendor,
+navigator.hardwareConcurrency, and navigator.deviceMemory consistently
 to avoid fingerprint inconsistencies.`,
         inputSchema: {
             type: 'object',
@@ -124,17 +127,17 @@ to avoid fingerprint inconsistencies.`,
     },
     {
         name: 'browser_list_tabs',
-        description: `List all open tabs/pages in the connected browser.
-
-Use this after browser_attach to see all available pages/tabs.
-Returns index, URL, and title for each tab.
-
-Workflow:
-1. browser_attach(browserURL="http://127.0.0.1:9222")
-2. browser_list_tabs() -> see all tabs with their indexes
-3. browser_select_tab(index=N) -> switch to desired tab
-
-Can also connect and list in one call:
+        description: `List all open tabs/pages in the connected browser.
+
+Use this after browser_attach to see all available pages/tabs.
+Returns index, URL, and title for each tab.
+
+Workflow:
+1. browser_attach(browserURL="http://127.0.0.1:9222")
+2. browser_list_tabs() -> see all tabs with their indexes
+3. browser_select_tab(index=N) -> switch to desired tab
+
+Can also connect and list in one call:
 browser_list_tabs(browserURL="http://127.0.0.1:9222")`,
         inputSchema: {
             type: 'object',
@@ -148,14 +151,14 @@ browser_list_tabs(browserURL="http://127.0.0.1:9222")`,
     },
     {
         name: 'browser_select_tab',
-        description: `Switch the active tab/page by index or URL/title pattern.
-
-After browser_list_tabs, use this to activate a specific tab.
-All subsequent page_* tools will operate on the selected tab.
-
-Examples:
-- browser_select_tab(index=0) -> first tab
-- browser_select_tab(urlPattern="qwen") -> tab whose URL contains "qwen"
+        description: `Switch the active tab/page by index or URL/title pattern.
+
+After browser_list_tabs, use this to activate a specific tab.
+All subsequent page_* tools will operate on the selected tab.
+
+Examples:
+- browser_select_tab(index=0) -> first tab
+- browser_select_tab(urlPattern="qwen") -> tab whose URL contains "qwen"
 - browser_select_tab(titlePattern="Mini Program") -> tab whose title contains "Mini Program"`,
         inputSchema: {
             type: 'object',

package/dist/server/domains/browser/handlers/camoufox-flow.js

@@ -75,7 +75,6 @@ export async function handleCamoufoxNavigateFlow(context, args) {
                 text: JSON.stringify({
                     success: true,
                     driver: 'camoufox',
-                    captcha_detected: false,
                     url: page.url(),
                     title: await page.title(),
                 }, null, 2),

package/dist/server/domains/browser/handlers/captcha-solver.d.ts

@@ -1,3 +1,3 @@
 import type { CodeCollector } from '../../../domains/shared/modules.js';
 export declare function handleCaptchaVisionSolve(args: Record<string, unknown>, collector: CodeCollector): Promise<unknown>;
-export declare function handleTurnstileSolve(args: Record<string, unknown>, collector: CodeCollector): Promise<unknown>;
+export declare function handleWidgetChallengeSolve(args: Record<string, unknown>, collector: CodeCollector): Promise<unknown>;