@jshookmcp/jshook 0.1.7 → 0.1.8

package/dist/server/domains/analysis/handlers.impl.js

@@ -1,12 +1,12 @@
 import { logger } from '../../../utils/logger.js';
 import { asJsonResponse, asTextResponse, serializeError } from '../../domains/shared/response.js';
 import { runSourceMapExtract, runWebpackEnumerate } from '../../domains/analysis/handlers.web-tools.js';
+import { runWebcrack } from '../../../modules/deobfuscator/webcrack.js';
 export class CoreAnalysisHandlers {
     collector;
     scriptManager;
     deobfuscator;
     advancedDeobfuscator;
-    astOptimizer;
     obfuscationDetector;
     analyzer;
     cryptoDetector;
@@ -16,7 +16,6 @@ export class CoreAnalysisHandlers {
         this.scriptManager = deps.scriptManager;
         this.deobfuscator = deps.deobfuscator;
         this.advancedDeobfuscator = deps.advancedDeobfuscator;
-        this.astOptimizer = deps.astOptimizer;
         this.obfuscationDetector = deps.obfuscationDetector;
         this.analyzer = deps.analyzer;
         this.cryptoDetector = deps.cryptoDetector;
@@ -30,6 +29,33 @@ export class CoreAnalysisHandlers {
         }
         return code;
     }
+    extractWebcrackArgs(args) {
+        const extracted = {};
+        if (typeof args.unpack === 'boolean')
+            extracted.unpack = args.unpack;
+        if (typeof args.unminify === 'boolean')
+            extracted.unminify = args.unminify;
+        if (typeof args.jsx === 'boolean')
+            extracted.jsx = args.jsx;
+        if (typeof args.mangle === 'boolean')
+            extracted.mangle = args.mangle;
+        if (typeof args.outputDir === 'string' && args.outputDir.trim().length > 0) {
+            extracted.outputDir = args.outputDir;
+        }
+        if (typeof args.forceOutput === 'boolean')
+            extracted.forceOutput = args.forceOutput;
+        if (typeof args.includeModuleCode === 'boolean')
+            extracted.includeModuleCode = args.includeModuleCode;
+        if (typeof args.maxBundleModules === 'number')
+            extracted.maxBundleModules = args.maxBundleModules;
+        if (Array.isArray(args.mappings)) {
+            extracted.mappings = args.mappings.filter((item) => typeof item === 'object' &&
+                item !== null &&
+                typeof item.path === 'string' &&
+                typeof item.pattern === 'string');
+        }
+        return extracted;
+    }
     async handleCollectCode(args) {
         const returnSummaryOnly = args.returnSummaryOnly ?? false;
         let smartMode = args.smartMode;
@@ -200,6 +226,7 @@ export class CoreAnalysisHandlers {
             code,
             llm: args.llm,
             aggressive: args.aggressive,
+            ...this.extractWebcrackArgs(args),
         });
         return asJsonResponse(result);
     }
@@ -280,24 +307,42 @@ export class CoreAnalysisHandlers {
                 error: 'code is required and must be a non-empty string',
             });
         }
-        const detectOnly = args.detectOnly ?? false;
-        const aggressiveVM = args.aggressiveVM ?? false;
-        const useASTOptimization = args.useASTOptimization ?? true;
-        const timeout = args.timeout ?? 60000;
         const result = await this.advancedDeobfuscator.deobfuscate({
             code,
-            detectOnly,
-            aggressiveVM,
-            timeout,
+            ...this.extractWebcrackArgs(args),
+            ...(typeof args.detectOnly === 'boolean' ? { detectOnly: args.detectOnly } : {}),
+            ...(typeof args.aggressiveVM === 'boolean' ? { aggressiveVM: args.aggressiveVM } : {}),
+            ...(typeof args.useASTOptimization === 'boolean'
+                ? { useASTOptimization: args.useASTOptimization }
+                : {}),
+            ...(typeof args.timeout === 'number' ? { timeout: args.timeout } : {}),
         });
-        let finalCode = result.code;
-        if (useASTOptimization && !detectOnly) {
-            finalCode = this.astOptimizer.optimize(finalCode);
+        return asJsonResponse(result);
+    }
+    async handleWebcrackUnpack(args) {
+        const code = this.requireCodeArg(args, 'webcrack_unpack');
+        if (!code) {
+            return asJsonResponse({
+                success: false,
+                error: 'code is required and must be a non-empty string',
+            });
         }
+        const result = await runWebcrack(code, {
+            unpack: args.unpack ?? true,
+            unminify: args.unminify ?? true,
+            jsx: args.jsx ?? true,
+            mangle: args.mangle ?? false,
+            ...this.extractWebcrackArgs(args),
+        });
         return asJsonResponse({
-            ...result,
-            code: finalCode,
-            astOptimized: useASTOptimization && !detectOnly,
+            success: result.applied,
+            code: result.code,
+            bundle: result.bundle,
+            savedTo: result.savedTo,
+            savedArtifacts: result.savedArtifacts,
+            optionsUsed: result.optionsUsed,
+            warning: result.reason,
+            engine: 'webcrack',
         });
     }
     async handleWebpackEnumerate(args) {

package/dist/server/domains/analysis/manifest.js

@@ -3,7 +3,6 @@ import { coreTools } from '../../domains/analysis/definitions.js';
 import { CoreAnalysisHandlers } from '../../domains/analysis/index.js';
 import { Deobfuscator } from '../../domains/shared/modules.js';
 import { AdvancedDeobfuscator } from '../../domains/shared/modules.js';
-import { ASTOptimizer } from '../../domains/shared/modules.js';
 import { ObfuscationDetector } from '../../domains/shared/modules.js';
 import { CodeAnalyzer } from '../../domains/shared/modules.js';
 import { CryptoDetector } from '../../domains/shared/modules.js';
@@ -17,9 +16,7 @@ function ensure(ctx) {
     if (!ctx.deobfuscator)
         ctx.deobfuscator = new Deobfuscator(ctx.llm);
     if (!ctx.advancedDeobfuscator)
-        ctx.advancedDeobfuscator = new AdvancedDeobfuscator(ctx.llm);
-    if (!ctx.astOptimizer)
-        ctx.astOptimizer = new ASTOptimizer();
+        ctx.advancedDeobfuscator = new AdvancedDeobfuscator();
     if (!ctx.obfuscationDetector)
         ctx.obfuscationDetector = new ObfuscationDetector();
     if (!ctx.analyzer)
@@ -34,7 +31,6 @@ function ensure(ctx) {
             scriptManager: ctx.scriptManager,
             deobfuscator: ctx.deobfuscator,
             advancedDeobfuscator: ctx.advancedDeobfuscator,
-            astOptimizer: ctx.astOptimizer,
             obfuscationDetector: ctx.obfuscationDetector,
             analyzer: ctx.analyzer,
             cryptoDetector: ctx.cryptoDetector,
@@ -60,6 +56,7 @@ const manifest = {
         { tool: t('manage_hooks'), domain: DOMAIN, bind: b((h, a) => h.handleManageHooks(a)) },
         { tool: t('detect_obfuscation'), domain: DOMAIN, bind: b((h, a) => h.handleDetectObfuscation(a)) },
         { tool: t('advanced_deobfuscate'), domain: DOMAIN, bind: b((h, a) => h.handleAdvancedDeobfuscate(a)) },
+        { tool: t('webcrack_unpack'), domain: DOMAIN, bind: b((h, a) => h.handleWebcrackUnpack(a)) },
         { tool: t('clear_collected_data'), domain: DOMAIN, bind: b((h) => h.handleClearCollectedData()) },
         { tool: t('get_collection_stats'), domain: DOMAIN, bind: b((h) => h.handleGetCollectionStats()) },
         { tool: t('webpack_enumerate'), domain: DOMAIN, bind: b((h, a) => h.handleWebpackEnumerate(a)) },

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.security.js

@@ -11,22 +11,23 @@ Detection process:
 Supported CAPTCHA types:
 - Slider CAPTCHA: drag-to-verify style challenges
 - Image CAPTCHA: select-images challenges
-- reCAPTCHA / hCaptcha
-- Cloudflare Challenge
+- 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
-- vendor: vendor name if identified
+- providerHint: broad provider category if identified
 - confidence: detection confidence (0-100)
 - reasoning: AI analysis explanation
-- screenshot: base64 screenshot (if MCP cannot view images, use external AI)
+- screenshotPath: saved screenshot path when a vision-capable model is unavailable
 - 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.`,
+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: {},
@@ -38,10 +39,12 @@ Use an external AI (GPT-4o, Claude 3) to analyze the screenshot.`,
 
 Steps:
 1. CAPTCHA is detected on the page
-2. Browser switches to headed (visible) mode
-3. User solves the CAPTCHA manually
+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',
@@ -59,8 +62,8 @@ Timeout: default 300000ms (5 minutes)`,
         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)
+- 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',

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>;

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

@@ -1,5 +1,5 @@
 import { logger } from '../../../../utils/logger.js';
-import { CAPTCHA_2CAPTCHA_BASE_URL, CAPTCHA_SUBMIT_TIMEOUT_MS, CAPTCHA_POLL_INTERVAL_MS, CAPTCHA_RESULT_TIMEOUT_MS, CAPTCHA_DEFAULT_TIMEOUT_MS, CAPTCHA_MIN_TIMEOUT_MS, CAPTCHA_MAX_TIMEOUT_MS, CAPTCHA_MAX_RETRIES, CAPTCHA_DEFAULT_RETRIES, } from '../../../../constants.js';
+import { CAPTCHA_SOLVER_BASE_URL, CAPTCHA_SUBMIT_TIMEOUT_MS, CAPTCHA_POLL_INTERVAL_MS, CAPTCHA_RESULT_TIMEOUT_MS, CAPTCHA_DEFAULT_TIMEOUT_MS, CAPTCHA_MIN_TIMEOUT_MS, CAPTCHA_MAX_TIMEOUT_MS, CAPTCHA_MAX_RETRIES, CAPTCHA_DEFAULT_RETRIES, } from '../../../../constants.js';
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -14,15 +14,64 @@ function toErrorResponse(tool, error, extra = {}) {
         ...extra,
     });
 }
+function normalizeSolverMode(rawMode) {
+    const value = typeof rawMode === 'string' ? rawMode.toLowerCase() : '';
+    if (value === 'hook')
+        return 'hook';
+    if (value === 'external_service')
+        return 'external_service';
+    if (value === '2captcha' || value === 'anticaptcha' || value === 'capsolver') {
+        return 'external_service';
+    }
+    return 'manual';
+}
+function normalizeChallengeTypeHint(rawType) {
+    const value = typeof rawType === 'string' ? rawType.toLowerCase() : '';
+    if (value === 'image')
+        return 'image';
+    if (value === 'widget' ||
+        value === 'recaptcha_v2' ||
+        value === 'recaptcha_v3' ||
+        value === 'hcaptcha' ||
+        value === 'funcaptcha' ||
+        value === 'turnstile') {
+        return 'widget';
+    }
+    if (value === 'browser_check' || value === 'managed_widget') {
+        return 'browser_check';
+    }
+    return 'auto';
+}
+function resolveLegacyServiceOverride(rawProvider) {
+    if (typeof rawProvider !== 'string' || !rawProvider.trim()) {
+        return undefined;
+    }
+    return rawProvider.trim().toLowerCase();
+}
+function resolveExternalServiceName(args) {
+    const legacyOverride = resolveLegacyServiceOverride(args.provider);
+    const configured = (process.env.CAPTCHA_PROVIDER || '').trim().toLowerCase();
+    return legacyOverride || configured || '2captcha';
+}
 async function solveWith2Captcha(apiKey, params, timeoutMs) {
     const start = Date.now();
-    const baseUrl = CAPTCHA_2CAPTCHA_BASE_URL;
+    const baseUrl = CAPTCHA_SOLVER_BASE_URL;
+    if (!baseUrl) {
+        throw new Error('CAPTCHA_SOLVER_BASE_URL must be configured before using external_service mode.');
+    }
     const submitBody = {
         key: apiKey,
         json: 1,
     };
-    if (params.type === 'turnstile' || params.type === 'recaptcha_v2' || params.type === 'hcaptcha') {
-        submitBody.method = params.type === 'turnstile' ? 'turnstile' : params.type === 'hcaptcha' ? 'hcaptcha' : 'userrecaptcha';
+    if (params.taskKind === 'turnstile' ||
+        params.taskKind === 'recaptcha_v2' ||
+        params.taskKind === 'hcaptcha') {
+        submitBody.method =
+            params.taskKind === 'turnstile'
+                ? 'turnstile'
+                : params.taskKind === 'hcaptcha'
+                    ? 'hcaptcha'
+                    : 'userrecaptcha';
         submitBody.sitekey = params.siteKey;
         submitBody.pageurl = params.pageUrl;
     }
@@ -61,8 +110,8 @@ async function solveWith2Captcha(apiKey, params, timeoutMs) {
         if (resultData.status === 1) {
             return {
                 token: resultData.request,
-                type: params.type,
-                provider: '2captcha',
+                challengeType: params.taskKind === 'image' ? 'image' : 'widget',
+                mode: 'external_service',
                 durationMs: Date.now() - start,
             };
         }
@@ -76,73 +125,87 @@ export async function handleCaptchaVisionSolve(args, collector) {
     const page = await collector.getActivePage();
     if (!page)
         throw new Error('No active page.');
-    const provider = args.provider || process.env.CAPTCHA_PROVIDER || 'manual';
+    const mode = normalizeSolverMode(args.mode ?? args.provider ?? process.env.CAPTCHA_PROVIDER);
+    const externalService = resolveExternalServiceName(args);
     const apiKey = args.apiKey || process.env.CAPTCHA_API_KEY || '';
-    const typeHint = args.typeHint || 'auto';
+    const challengeTypeHint = normalizeChallengeTypeHint(args.challengeType ?? args.typeHint);
     const timeoutMs = Math.min(Math.max(args.timeoutMs ?? CAPTCHA_DEFAULT_TIMEOUT_MS, CAPTCHA_MIN_TIMEOUT_MS), CAPTCHA_MAX_TIMEOUT_MS);
     const maxRetries = Math.min(Math.max(args.maxRetries ?? CAPTCHA_DEFAULT_RETRIES, 0), CAPTCHA_MAX_RETRIES);
-    let captchaType = typeHint;
+    let challengeType = challengeTypeHint;
+    let taskKind = challengeTypeHint === 'image' ? 'image' : 'recaptcha_v2';
     let siteKey = args.siteKey;
     const pageUrl = args.pageUrl || page.url();
-    if (captchaType === 'auto') {
+    if (challengeType === 'auto') {
         const detected = await page.evaluate(() => {
             if (document.querySelector('[data-sitekey]')) {
                 const el = document.querySelector('[data-sitekey]');
                 const sk = el?.getAttribute('data-sitekey') || '';
-                if (document.querySelector('.cf-turnstile'))
-                    return { type: 'turnstile', siteKey: sk };
-                if (document.querySelector('.h-captcha'))
-                    return { type: 'hcaptcha', siteKey: sk };
-                return { type: 'recaptcha_v2', siteKey: sk };
+                if (document.querySelector('.cf-turnstile')) {
+                    return { challengeType: 'widget', taskKind: 'turnstile', siteKey: sk };
+                }
+                if (document.querySelector('.h-captcha')) {
+                    return { challengeType: 'widget', taskKind: 'hcaptcha', siteKey: sk };
+                }
+                return { challengeType: 'widget', taskKind: 'recaptcha_v2', siteKey: sk };
+            }
+            if (document.querySelector('iframe[src*="recaptcha"]')) {
+                return { challengeType: 'widget', taskKind: 'recaptcha_v2', siteKey: '' };
+            }
+            if (document.querySelector('iframe[src*="hcaptcha"]')) {
+                return { challengeType: 'widget', taskKind: 'hcaptcha', siteKey: '' };
             }
-            if (document.querySelector('iframe[src*="recaptcha"]'))
-                return { type: 'recaptcha_v2', siteKey: '' };
-            if (document.querySelector('iframe[src*="hcaptcha"]'))
-                return { type: 'hcaptcha', siteKey: '' };
-            if (document.querySelector('.cf-turnstile'))
-                return { type: 'turnstile', siteKey: '' };
-            return { type: 'image', siteKey: '' };
+            if (document.querySelector('.cf-turnstile')) {
+                return { challengeType: 'widget', taskKind: 'turnstile', siteKey: '' };
+            }
+            return { challengeType: 'image', taskKind: 'image', siteKey: '' };
         });
-        captchaType = detected.type;
+        challengeType = detected.challengeType;
+        taskKind = detected.taskKind;
         if (!siteKey && detected.siteKey)
             siteKey = detected.siteKey;
     }
-    if (provider === 'manual') {
+    else if (challengeType === 'image') {
+        taskKind = 'image';
+    }
+    else {
+        taskKind = 'recaptcha_v2';
+    }
+    if (mode === 'manual') {
         return toTextResponse({
             success: true,
             mode: 'manual',
-            captchaType,
+            challengeType,
             siteKey: siteKey ?? null,
             instruction: 'Please solve the CAPTCHA manually in the browser, then continue.',
-            hint: 'Set CAPTCHA_PROVIDER and CAPTCHA_API_KEY env vars for automatic solving.',
+            hint: 'Configure an external solver service and CAPTCHA_API_KEY to automate this flow.',
         });
     }
     if (!apiKey) {
-        return toErrorResponse('captcha_vision_solve', new Error(`API key required for provider "${provider}". Set CAPTCHA_API_KEY env var.`));
+        return toErrorResponse('captcha_vision_solve', new Error('External solver credentials are required. Set CAPTCHA_API_KEY.'));
     }
     let lastError = null;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             let result;
-            if (provider === '2captcha') {
+            if (externalService === '2captcha') {
                 result = await solveWith2Captcha(apiKey, {
-                    type: captchaType,
+                    taskKind,
                     siteKey,
                     pageUrl,
                 }, timeoutMs);
             }
-            else if (provider === 'anticaptcha' || provider === 'capsolver') {
-                throw new Error(`Provider "${provider}" is not yet implemented. ` +
-                    `Currently only "2captcha" and "manual" are supported.`);
+            else if (externalService === 'anticaptcha' || externalService === 'capsolver') {
+                throw new Error('The selected external solver service is not yet implemented. ' +
+                    'Currently only the configured primary service and manual mode are supported.');
             }
             else {
-                throw new Error(`Unsupported provider: ${provider}`);
+                throw new Error('Unsupported external solver service.');
             }
             return toTextResponse({
                 success: true,
                 token: result.token,
-                captchaType: result.type,
-                provider: result.provider,
+                challengeType: result.challengeType,
+                mode: result.mode,
                 durationMs: result.durationMs,
                 attempt: attempt + 1,
             });
@@ -153,17 +216,18 @@ export async function handleCaptchaVisionSolve(args, collector) {
         }
     }
     return toErrorResponse('captcha_vision_solve', lastError ?? new Error('All attempts failed'), {
-        captchaType,
-        provider,
+        challengeType,
+        mode,
         maxRetries,
-        suggestion: 'Try a different provider or solve manually.',
+        suggestion: 'Try manual mode or adjust the external solver configuration.',
     });
 }
-export async function handleTurnstileSolve(args, collector) {
+export async function handleWidgetChallengeSolve(args, collector) {
     const page = await collector.getActivePage();
     if (!page)
         throw new Error('No active page.');
-    const provider = args.provider || process.env.CAPTCHA_PROVIDER || 'manual';
+    const mode = normalizeSolverMode(args.mode ?? args.provider ?? process.env.CAPTCHA_PROVIDER);
+    const externalService = resolveExternalServiceName(args);
     const apiKey = args.apiKey || process.env.CAPTCHA_API_KEY || '';
     const timeoutMs = Math.min(Math.max(args.timeoutMs ?? 120_000, 5_000), 600_000);
     const injectToken = args.injectToken ?? true;
@@ -176,9 +240,9 @@ export async function handleTurnstileSolve(args, collector) {
         }) || undefined;
     }
     if (!siteKey) {
-        return toErrorResponse('turnstile_solve', new Error('Could not detect Turnstile siteKey. Provide it manually or ensure the page has a Turnstile widget.'));
+        return toErrorResponse('widget_challenge_solve', new Error('Could not detect the widget siteKey. Provide it manually or ensure the page exposes a site key.'));
     }
-    if (provider === 'hook') {
+    if (mode === 'hook') {
         const hookTimeoutMs = Math.min(timeoutMs, 30_000);
         const token = await page.evaluate((hookTimeout) => {
             return new Promise((resolve, reject) => {
@@ -195,7 +259,7 @@ export async function handleTurnstileSolve(args, collector) {
                 }
                 else {
                     clearTimeout(timeout);
-                    reject(new Error('No turnstile callbacks found. Try provider: "2captcha" instead.'));
+                    reject(new Error('No widget callbacks found. Try external_service mode instead.'));
                 }
             });
         }, hookTimeoutMs).catch(() => null);
@@ -204,29 +268,31 @@ export async function handleTurnstileSolve(args, collector) {
                 success: true,
                 token,
                 method: 'hook',
+                challengeType: 'widget',
                 siteKey,
             });
         }
     }
-    if (provider === 'manual') {
+    if (mode === 'manual') {
         return toTextResponse({
             success: true,
             mode: 'manual',
+            challengeType: 'widget',
             siteKey,
             pageUrl,
-            instruction: 'Please complete the Turnstile challenge manually.',
+            instruction: 'Please complete the widget challenge manually.',
         });
     }
-    if (provider !== '2captcha') {
-        return toErrorResponse('turnstile_solve', new Error(`Provider "${provider}" is not yet implemented for Turnstile. ` +
-            `Currently only "2captcha", "manual", and "hook" are supported.`));
+    if (externalService !== '2captcha') {
+        return toErrorResponse('widget_challenge_solve', new Error('The selected external solver service is not implemented for this widget flow. ' +
+            'Currently only the configured primary service, manual mode, and hook mode are supported.'));
     }
     if (!apiKey) {
-        return toErrorResponse('turnstile_solve', new Error('API key required'));
+        return toErrorResponse('widget_challenge_solve', new Error('External solver credentials are required.'));
     }
     try {
         const result = await solveWith2Captcha(apiKey, {
-            type: 'turnstile',
+            taskKind: 'turnstile',
             siteKey,
             pageUrl,
         }, timeoutMs);
@@ -244,17 +310,18 @@ export async function handleTurnstileSolve(args, collector) {
         return toTextResponse({
             success: true,
             token: result.token,
+            challengeType: result.challengeType,
             siteKey,
-            provider: result.provider,
+            mode: result.mode,
             durationMs: result.durationMs,
             injected: injectToken,
         });
     }
     catch (error) {
-        return toErrorResponse('turnstile_solve', error, {
+        return toErrorResponse('widget_challenge_solve', error, {
             siteKey,
-            provider,
-            suggestion: 'Try provider: "manual" or provider: "hook".',
+            mode,
+            suggestion: 'Try manual mode or hook mode.',
         });
     }
 }