@jshookmcp/jshook 0.2.3 → 0.2.5

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

@@ -1,341 +1,196 @@
+import { tool } from '../../registry/tool-builder.js';
 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
-- 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: {},
-        },
-    },
-    {
-        name: 'captcha_wait',
-        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',
-            properties: {
-                timeout: {
-                    type: 'number',
-                    description: 'Timeout in milliseconds (default: 300000 = 5 minutes)',
-                    default: 300000,
-                },
-            },
-        },
-    },
-    {
-        name: 'captcha_config',
-        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',
-            properties: {
-                autoDetectCaptcha: {
-                    type: 'boolean',
-                    description: 'Whether to automatically detect CAPTCHA after navigation',
-                },
-                autoSwitchHeadless: {
-                    type: 'boolean',
-                    description: 'Whether to automatically switch to headed mode when CAPTCHA detected',
-                },
-                captchaTimeout: {
-                    type: 'number',
-                    description: 'Timeout for waiting user to complete CAPTCHA (milliseconds)',
-                },
-            },
-        },
-    },
-    {
-        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.
-Call after browser_launch for best results.`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        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
-to avoid fingerprint inconsistencies.
-
-UA strings are updated to Chrome 131 with platform-appropriate hardware profiles.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                platform: {
-                    type: 'string',
-                    description: 'Target platform',
-                    enum: ['windows', 'mac', 'linux'],
-                    default: 'windows',
-                },
-            },
-        },
-    },
-    {
-        name: 'stealth_configure_jitter',
-        description: `Configure CDP command timing jitter to mimic natural network latency.
-
-Jitter adds random delays to CDP commands to prevent timing-based bot detection.
-Default: 20-80ms uniform random delay on all CDP send() calls.
-
-Parameters:
-- enabled: turn jitter on/off
-- minDelayMs: minimum delay in milliseconds
-- maxDelayMs: maximum delay in milliseconds
-- burstMode: skip jitter for time-critical operations (debugging, breakpoints)`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                enabled: {
-                    type: 'boolean',
-                    description: 'Enable/disable jitter',
-                    default: true,
-                },
-                minDelayMs: {
-                    type: 'number',
-                    description: 'Minimum delay (ms)',
-                    default: 20,
-                },
-                maxDelayMs: {
-                    type: 'number',
-                    description: 'Maximum delay (ms)',
-                    default: 80,
-                },
-                burstMode: {
-                    type: 'boolean',
-                    description: 'Skip jitter for time-critical ops',
-                    default: false,
-                },
-            },
-        },
-    },
-    {
-        name: 'stealth_generate_fingerprint',
-        description: `Generate a realistic browser fingerprint using real-world datasets.
-
-Requires fingerprint-generator and fingerprint-injector packages (optional dependencies).
-The generated fingerprint is cached per session and auto-applied on next stealth_inject.
-
-Covers: screen resolution, WebGL params, fonts, codecs, AudioContext, navigator properties.
-Falls back to built-in StealthScripts patches if packages are not installed.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                os: {
-                    type: 'string',
-                    description: 'Target OS for fingerprint',
-                    enum: ['windows', 'macos', 'linux'],
-                },
-                browser: {
-                    type: 'string',
-                    description: 'Target browser',
-                    enum: ['chrome', 'firefox'],
-                    default: 'chrome',
-                },
-                locale: {
-                    type: 'string',
-                    description: 'Locale string (e.g. en-US)',
-                    default: 'en-US',
-                },
-            },
-        },
-    },
-    {
-        name: 'stealth_verify',
-        description: `Run offline anti-detection checks on the current page.
-
-Verifies that stealth patches are working correctly by checking:
-- navigator.webdriver absence
-- window.chrome object structure
-- navigator.plugins list
-- UA/platform consistency
-- WebGL vendor/renderer
-- Canvas noise injection
-- cdc_ variable cleanup
-- Hardware profile consistency
-
-Returns a structured report with pass/fail for each check, an overall score (0-100),
-and recommendations for improving detection evasion.
-
-Best used after stealth_inject to verify patches are effective.`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        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") or browser_attach(autoConnect=true)
-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")
-browser_list_tabs(autoConnect=true, channel="stable")`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                browserURL: {
-                    type: 'string',
-                    description: 'Optional: connect to this browser URL before listing (e.g. http://127.0.0.1:9222)',
-                },
-                wsEndpoint: {
-                    type: 'string',
-                    description: 'Optional: connect to this browser WebSocket endpoint before listing.',
-                },
-                autoConnect: {
-                    type: 'boolean',
-                    description: 'Chrome 144+ only. Auto-detect the local Chrome debugging WebSocket from DevToolsActivePort. Requires remote debugging to be enabled at chrome://inspect/#remote-debugging, and Chrome may prompt you to manually approve this client.',
-                    default: false,
-                },
-                channel: {
-                    type: 'string',
-                    description: 'Chrome channel used for autoConnect when userDataDir is not provided.',
-                    enum: ['stable', 'beta', 'dev', 'canary'],
-                    default: 'stable',
-                },
-                userDataDir: {
-                    type: 'string',
-                    description: 'Optional Chrome profile directory for autoConnect. If omitted, the default profile path for the selected channel is used.',
-                },
-            },
-        },
-    },
-    {
-        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"
-- browser_select_tab(titlePattern="Mini Program") -> tab whose title contains "Mini Program"`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                index: {
-                    type: 'number',
-                    description: 'Tab index from browser_list_tabs (0-based)',
-                },
-                urlPattern: {
-                    type: 'string',
-                    description: 'Substring to match against tab URLs',
-                },
-                titlePattern: {
-                    type: 'string',
-                    description: 'Substring to match against tab titles',
-                },
-            },
-        },
-    },
-    {
-        name: 'framework_state_extract',
-        description: 'Extract component state from the live page. Supports React, Vue 2/3, Svelte 3/4/5, Solid.js, and Preact. Also detects Next.js/Nuxt meta-framework metadata (routes, build info, payload). Useful for debugging frontend applications, reverse-engineering SPA state, and finding hidden data.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                framework: {
-                    type: 'string',
-                    description: 'Framework to target. auto = detect automatically.',
-                    enum: ['auto', 'react', 'vue2', 'vue3', 'svelte', 'solid', 'preact'],
-                    default: 'auto',
-                },
-                selector: {
-                    type: 'string',
-                    description: 'CSS selector of root element to inspect (default: #root, #app, [data-reactroot], body)',
-                },
-                maxDepth: {
-                    type: 'number',
-                    description: 'Maximum component tree depth to traverse',
-                    default: 5,
-                },
-            },
-        },
-    },
-    {
-        name: 'indexeddb_dump',
-        description: 'Dump all IndexedDB databases and their contents. Useful for analyzing PWA data, stored tokens, or offline application state.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                database: {
-                    type: 'string',
-                    description: 'Specific database name to dump (default: all databases)',
-                },
-                store: {
-                    type: 'string',
-                    description: 'Specific object store to dump (default: all stores)',
-                },
-                maxRecords: {
-                    type: 'number',
-                    description: 'Maximum records per store to return',
-                    default: 100,
-                },
-            },
-        },
-    },
+    tool('captcha_detect')
+        .desc(`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.`)
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('captcha_wait')
+        .desc(`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)`)
+        .number('timeout', 'Timeout in milliseconds (default: 300000 = 5 minutes)', { default: 300000 })
+        .readOnly()
+        .idempotent()
+        .openWorld()
+        .build(),
+    tool('captcha_config')
+        .desc(`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)`)
+        .boolean('autoDetectCaptcha', 'Whether to automatically detect CAPTCHA after navigation')
+        .boolean('autoSwitchHeadless', 'Whether to automatically switch to headed mode when CAPTCHA detected')
+        .number('captchaTimeout', 'Timeout for waiting user to complete CAPTCHA (milliseconds)')
+        .idempotent()
+        .build(),
+    tool('stealth_inject')
+        .desc(`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.`)
+        .idempotent()
+        .build(),
+    tool('stealth_set_user_agent')
+        .desc(`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.
+
+UA strings are updated to Chrome 131 with platform-appropriate hardware profiles.`)
+        .enum('platform', ['windows', 'mac', 'linux'], 'Target platform', { default: 'windows' })
+        .idempotent()
+        .build(),
+    tool('stealth_configure_jitter')
+        .desc(`Configure CDP command timing jitter to mimic natural network latency.
+
+Jitter adds random delays to CDP commands to prevent timing-based bot detection.
+Default: 20-80ms uniform random delay on all CDP send() calls.
+
+Parameters:
+- enabled: turn jitter on/off
+- minDelayMs: minimum delay in milliseconds
+- maxDelayMs: maximum delay in milliseconds
+- burstMode: skip jitter for time-critical operations (debugging, breakpoints)`)
+        .boolean('enabled', 'Enable/disable jitter', { default: true })
+        .number('minDelayMs', 'Minimum delay (ms)', { default: 20 })
+        .number('maxDelayMs', 'Maximum delay (ms)', { default: 80 })
+        .boolean('burstMode', 'Skip jitter for time-critical ops', { default: false })
+        .idempotent()
+        .build(),
+    tool('stealth_generate_fingerprint')
+        .desc(`Generate a realistic browser fingerprint using real-world datasets.
+
+Requires fingerprint-generator and fingerprint-injector packages (optional dependencies).
+The generated fingerprint is cached per session and auto-applied on next stealth_inject.
+
+Covers: screen resolution, WebGL params, fonts, codecs, AudioContext, navigator properties.
+Falls back to built-in StealthScripts patches if packages are not installed.`)
+        .enum('os', ['windows', 'macos', 'linux'], 'Target OS for fingerprint')
+        .enum('browser', ['chrome', 'firefox'], 'Target browser', { default: 'chrome' })
+        .string('locale', 'Locale string (e.g. en-US)', { default: 'en-US' })
+        .build(),
+    tool('stealth_verify')
+        .desc(`Run offline anti-detection checks on the current page.
+
+Verifies that stealth patches are working correctly by checking:
+- navigator.webdriver absence
+- window.chrome object structure
+- navigator.plugins list
+- UA/platform consistency
+- WebGL vendor/renderer
+- Canvas noise injection
+- cdc_ variable cleanup
+- Hardware profile consistency
+
+Returns a structured report with pass/fail for each check, an overall score (0-100),
+and recommendations for improving detection evasion.
+
+Best used after stealth_inject to verify patches are effective.`)
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('browser_list_tabs')
+        .desc(`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") or browser_attach(autoConnect=true)
+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")
+browser_list_tabs(autoConnect=true, channel="stable")`)
+        .string('browserURL', 'Optional: connect to this browser URL before listing (e.g. http://127.0.0.1:9222)')
+        .string('wsEndpoint', 'Optional: connect to this browser WebSocket endpoint before listing.')
+        .boolean('autoConnect', 'Chrome 144+ only. Auto-detect the local Chrome debugging WebSocket from DevToolsActivePort. Requires remote debugging to be enabled at chrome://inspect/#remote-debugging, and Chrome may prompt you to manually approve this client.', { default: false })
+        .enum('channel', ['stable', 'beta', 'dev', 'canary'], 'Chrome channel used for autoConnect when userDataDir is not provided.', { default: 'stable' })
+        .string('userDataDir', 'Optional Chrome profile directory for autoConnect. If omitted, the default profile path for the selected channel is used.')
+        .readOnly()
+        .idempotent()
+        .openWorld()
+        .build(),
+    tool('browser_select_tab')
+        .desc(`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"`)
+        .number('index', 'Tab index from browser_list_tabs (0-based)')
+        .string('urlPattern', 'Substring to match against tab URLs')
+        .string('titlePattern', 'Substring to match against tab titles')
+        .idempotent()
+        .build(),
+    tool('framework_state_extract')
+        .desc('Extract component state from the live page. Supports React, Vue 2/3, Svelte 3/4/5, Solid.js, and Preact. Also detects Next.js/Nuxt meta-framework metadata (routes, build info, payload). Useful for debugging frontend applications, reverse-engineering SPA state, and finding hidden data.')
+        .enum('framework', ['auto', 'react', 'vue2', 'vue3', 'svelte', 'solid', 'preact'], 'Framework to target. auto = detect automatically.', { default: 'auto' })
+        .string('selector', 'CSS selector of root element to inspect (default: #root, #app, [data-reactroot], body)')
+        .number('maxDepth', 'Maximum component tree depth to traverse', { default: 5 })
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('indexeddb_dump')
+        .desc('Dump all IndexedDB databases and their contents. Useful for analyzing PWA data, stored tokens, or offline application state.')
+        .string('database', 'Specific database name to dump (default: all databases)')
+        .string('store', 'Specific object store to dump (default: all stores)')
+        .number('maxRecords', 'Maximum records per store to return', { default: 100 })
+        .readOnly()
+        .idempotent()
+        .build(),
 ];

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

@@ -1,5 +1,6 @@
 import { CamoufoxBrowserManager } from '../../../domains/shared/modules.js';
 import { argString, argNumber, argBool } from '../../../domains/shared/parse-args.js';
+import { formatBetterSqlite3Error, isBetterSqlite3RelatedError } from '../../../../utils/betterSqlite3.js';
 import { logger } from '../../../../utils/logger.js';
 async function checkCamoufoxDependencies() {
     try {
@@ -8,8 +9,8 @@ async function checkCamoufoxDependencies() {
     }
     catch (error) {
         const errorMsg = error instanceof Error ? error.message : String(error);
-        if (errorMsg.includes('better-sqlite3') || errorMsg.includes('bindings file')) {
-            return `Camoufox requires native dependencies that are not installed. Run: pnpm add better-sqlite3 or npm rebuild better-sqlite3. Original error: ${errorMsg}`;
+        if (isBetterSqlite3RelatedError(error)) {
+            return `Camoufox requires the same native SQLite backend used by trace tooling. ${formatBetterSqlite3Error(error)}`;
         }
         if (errorMsg.includes("Cannot find package 'camoufox-js'")) {
             return 'camoufox-js package is not installed. Run: pnpm add camoufox-js && npx camoufox-js fetch';

package/dist/src/server/domains/browser/handlers/captcha-solver.js

@@ -254,10 +254,10 @@ export async function handleWidgetChallengeSolve(args, collector) {
                     .__turnstile_callbacks;
                 if (origCallbacks) {
                     for (const [key, cb] of Object.entries(origCallbacks)) {
-                        origCallbacks[key] = (token) => {
+                        origCallbacks[key] = (captchaToken) => {
                             clearTimeout(timeout);
-                            resolve(token);
-                            cb(token);
+                            resolve(captchaToken);
+                            cb(captchaToken);
                         };
                     }
                 }

package/dist/src/server/domains/browser/handlers/dom-query.js

@@ -35,7 +35,8 @@ export class DOMQueryHandlers {
         };
     }
     async handleDOMGetStructure(args) {
-        const maxDepth = argNumber(args, 'maxDepth', 3);
+        const MAX_DOM_DEPTH = 4;
+        const maxDepth = Math.min(argNumber(args, 'maxDepth', 3), MAX_DOM_DEPTH);
         const includeText = argBool(args, 'includeText', true);
         const structure = await this.deps.domInspector.getStructure(maxDepth, includeText);
         return {