mcp-web-inspector 0.4.5 → 0.5.3

package/README.md

@@ -595,7 +595,7 @@ COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in on
   - selector2 (string, required): CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')
 
 - Output Format:
-  - Optional warnings when a selector matched multiple elements (using first).
+  - Optional warnings when a selector matched multiple elements (uses first visible; suggests adding unique data-testid).
   - Header: Alignment: <elem1> vs <elem2>
   - Two lines with each element's position and size: @ (x,y) w×h px
   - Edges block: Top/Left/Right/Bottom with ✓/✗ and diffs
@@ -997,14 +997,13 @@ Upload a file to an input[type='file'] element on the page
 ### Content
 
 #### `get_html`
-⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements), shows preview with token-based confirmation if larger. Scripts removed by default for security/size. Supports testid shortcuts.
+⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output. Scripts removed by default for security/size. Supports testid shortcuts.
 
 - Parameters:
   - selector (string, optional): CSS selector, text selector, or testid shorthand to limit HTML extraction to a specific container. Omit to get entire page HTML. Example: 'testid:main-content' or '#app'
   - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
   - clean (boolean, optional): Remove noise from HTML: false (default) = remove scripts only, true = remove scripts + styles + comments + meta tags for minimal markup
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
-  - confirmToken (string, optional): Confirmation token from preview response (required to retrieve large HTML). Get this token by calling without confirmToken first - the preview will include the token to use.
 
 #### `get_text`
 ⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Returns plain text up to 20000 chars (truncated if longer). Supports testid shortcuts.
@@ -1032,8 +1031,6 @@ Upload a file to an input[type='file'] element on the page
 
 ⚠️ Token cost: ~1,500 tokens to read. Structural tools: <100 tokens.
 
-Admin control (optional): set env MCP_SCREENSHOT_GUARD=strict to block execution (prevents misuse by default). Unset to allow visuals for human review.
-
 Screenshots saved to ./.mcp-web-inspector/screenshots. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }
 
 - Parameters:
@@ -1048,7 +1045,7 @@ Screenshots saved to ./.mcp-web-inspector/screenshots. Example: { name: "login-p
 Clears captured console logs and returns the number of entries cleared.
 
 #### `get_console_logs`
-Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and require confirmToken to fetch the full payload.
+Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
 
 - Parameters:
   - type (string, optional): Type of logs to retrieve (all, error, warning, log, info, debug, exception)
@@ -1056,16 +1053,28 @@ Retrieve console logs with filtering and token‑efficient output. Defaults: sin
   - limit (number, optional): Maximum entries to return (groups when grouped, lines when raw). Default: 20
   - since (string, optional): Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.). Default: 'last-interaction'
   - format (string, optional): Output format: 'grouped' (default, deduped with counts) or 'raw' (chronological, ungrouped)
-  - confirmToken (string, optional): One-time token to return large outputs. Obtain it by calling without confirmToken to receive a preview.
 
 ### Evaluation
 
 #### `evaluate`
-⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return the result (JSON-stringified). ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_positions). Use ONLY when specialized tools cannot accomplish the task. Essential for: custom page interactions, complex calculations not covered by other tools. Automatically detects common patterns and suggests better alternatives. High flexibility but less efficient than specialized tools.
+⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return a compact, token-efficient summary of the result. Includes a large-output preview guard with a one-time token. ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_element_alignment). Use ONLY when specialized tools cannot accomplish the task. Automatically detects common patterns and suggests better alternatives.
 
 - Parameters:
   - script (string, required): JavaScript code to execute
 
+- Output Format:
+  - Header: '✓ JavaScript execution result:'
+  - Default result: compact summary string (arrays/objects/dom nodes summarized)
+  - Array summary: 'Array(n) [first, second, third…]' (shows first 3 items)
+  - Object summary (large): 'Object(n keys): key1, key2, key3…' (top-level keys only)
+  - DOM node summary: '<tag id=#id class=.a.b> @ (x,y) WxH' (rounded ints)
+  - NodeList/HTMLCollection summary: 'NodeList(n) [<div…>, <span…>, <a…>…]'
+  - Preview guard when result is large (≥ ~2000 chars):
+    - 'Preview (first 500 chars):' followed by excerpt
+    - Counts: 'totalLength: N, shownLength: M, truncated: true'
+    - One-time token string to fetch full output
+  - Suggestions block (conditional): compact tips for specialized tools based on script patterns
+
 ### Network
 
 #### `get_request_details`
@@ -1107,6 +1116,18 @@ Set the browser color scheme that controls CSS prefers-color-scheme. Defaults to
 
 - Parameters:
   - scheme (string, required): Color scheme to emulate: 'system', 'dark', 'light', or 'no-preference'. Example: { scheme: 'dark' }
+
+### Other
+
+#### `confirm_output`
+Return full output for a previously previewed large result using a one-time token. Use when a tool responded with a preview + token. Safer than resending original parameters.
+
+- Parameters:
+  - token (string, required): One-time token obtained from a tool's preview response
+
+- Output Format:
+  - Full original payload if token is valid (one-time)
+  - Error: 'Invalid or expired token'
 ## Selector Shortcuts ⭐ Time-Saver
 
 All browser tools support **convenient test ID shortcuts** that save typing and improve readability:

package/dist/tools/browser/base.d.ts

@@ -12,18 +12,23 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      */
     abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
     /**
-     * Normalize selector shortcuts to full Playwright selectors and clean common escaping mistakes
-     * - "testid:foo" → "[data-testid='foo']"
-     * - "data-test:bar" → "[data-test='bar']"
-     * - "data-cy:baz" → "[data-cy='baz']"
-     * - Removes unnecessary backslash escapes from CSS selectors that LLMs often add
-     * - ".dark\\:bg-gray-700" → ".dark:bg-gray-700"
-     * - ".top-\\[36px\\]" → ".top-[36px]"
-     * - ".top-\\\\[36px\\\\]" → ".top-[36px]" (double-escaped)
+     * Normalize selector shortcuts and fix common escaping mistakes safely.
+     * - "testid:foo" → "[data-testid=\"foo\"]"
+     * - "data-test:bar" → "[data-test=\"bar\"]"
+     * - "data-cy:baz" → "[data-cy=\"baz\"]"
+     * - Convert simple ID-only selectors with special chars to Playwright's id engine:
+     *     "#radix-\:rc\:-content-123" → "id=radix-:rc:-content-123"
+     * - Remove unnecessary escapes for bracket characters only (\\[ and \\])
+     *   DO NOT unescape colons globally — colons in class/ID names must stay escaped in CSS.
      * @param selector The selector string
      * @returns Normalized selector
      */
     protected normalizeSelector(selector: string): string;
+    /**
+     * Sanitize verbose Playwright selector engine messages by removing stack traces and
+     * keeping only the essential syntax error information.
+     */
+    protected sanitizeSelectorEngineMessage(msg: string): string;
     /**
      * Ensures a page is available and returns it
      * @param context The tool context containing browser and page

package/dist/tools/browser/base.js

@@ -8,14 +8,14 @@ export class BrowserToolBase {
         this.server = server;
     }
     /**
-     * Normalize selector shortcuts to full Playwright selectors and clean common escaping mistakes
-     * - "testid:foo" → "[data-testid='foo']"
-     * - "data-test:bar" → "[data-test='bar']"
-     * - "data-cy:baz" → "[data-cy='baz']"
-     * - Removes unnecessary backslash escapes from CSS selectors that LLMs often add
-     * - ".dark\\:bg-gray-700" → ".dark:bg-gray-700"
-     * - ".top-\\[36px\\]" → ".top-[36px]"
-     * - ".top-\\\\[36px\\\\]" → ".top-[36px]" (double-escaped)
+     * Normalize selector shortcuts and fix common escaping mistakes safely.
+     * - "testid:foo" → "[data-testid=\"foo\"]"
+     * - "data-test:bar" → "[data-test=\"bar\"]"
+     * - "data-cy:baz" → "[data-cy=\"baz\"]"
+     * - Convert simple ID-only selectors with special chars to Playwright's id engine:
+     *     "#radix-\:rc\:-content-123" → "id=radix-:rc:-content-123"
+     * - Remove unnecessary escapes for bracket characters only (\\[ and \\])
+     *   DO NOT unescape colons globally — colons in class/ID names must stay escaped in CSS.
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -32,16 +32,58 @@ export class BrowserToolBase {
                 return `[${attr}="${value}"]`;
             }
         }
-        // Clean up common escaping mistakes that LLMs make in CSS selectors
-        // These characters don't need to be escaped in CSS selectors: [ ] :
-        let cleaned = selector;
-        // Remove backslash escapes before brackets and colons
-        // Handle both single escapes (\[) and double escapes (\\[)
-        cleaned = cleaned.replace(/\\+\[/g, '[');
-        cleaned = cleaned.replace(/\\+\]/g, ']');
-        cleaned = cleaned.replace(/\\+:/g, ':');
+        const trimmed = selector.trim();
+        // Helper: unescape simple backslash-escapes used inside IDs (e.g., \:, \[, \])
+        const unescapeCssIdentifier = (s) => {
+            // Collapse multiple backslashes before a single char to the char itself
+            return s
+                .replace(/\\+:/g, ':')
+                .replace(/\\+\[/g, '[')
+                .replace(/\\+\]/g, ']');
+        };
+        // If this looks like a simple, standalone ID selector (no combinators or descendants),
+        // switch to Playwright's id engine. This avoids CSS escaping pitfalls with colons.
+        if (/^#[^\s>+~]+$/.test(trimmed)) {
+            const idToken = trimmed.slice(1);
+            // Only switch to id= engine if ID contains characters that commonly break CSS (#... with colons or escapes)
+            if (idToken.includes('\\') || idToken.includes(':') || idToken.includes('[') || idToken.includes(']')) {
+                const idValue = unescapeCssIdentifier(idToken);
+                return `id=${idValue}`;
+            }
+            // Otherwise, keep simple IDs as-is
+            return trimmed;
+        }
+        // For general CSS selectors, preserve required escapes for special chars.
+        // Collapse over-escaping (e.g., \\\\[ → \\[, but keep a single backslash before [ ] :)
+        let cleaned = trimmed;
+        cleaned = cleaned.replace(/\\{2,}(?=\[)/g, '\\');
+        cleaned = cleaned.replace(/\\{2,}(?=\])/g, '\\');
+        cleaned = cleaned.replace(/\\{2,}(?=:)/g, '\\');
         return cleaned;
     }
+    /**
+     * Sanitize verbose Playwright selector engine messages by removing stack traces and
+     * keeping only the essential syntax error information.
+     */
+    sanitizeSelectorEngineMessage(msg) {
+        if (!msg)
+            return '';
+        // Prefer to cut at the common phrase used by the browser
+        const cutoffPhrases = [
+            "is not a valid selector.",
+            "is not a valid selector",
+        ];
+        for (const phrase of cutoffPhrases) {
+            const idx = msg.indexOf(phrase);
+            if (idx !== -1) {
+                return msg.slice(0, idx + phrase.length).trim();
+            }
+        }
+        // Otherwise remove stack-like lines (e.g., " at query (…)")
+        const lines = msg.split(/\r?\n/);
+        const filtered = lines.filter(l => !/^\s*at\b/.test(l) && !/<anonymous>:\d+:\d+/.test(l));
+        return filtered.join('\n').trim();
+    }
     /**
      * Ensures a page is available and returns it
      * @param context The tool context containing browser and page
@@ -164,20 +206,23 @@ export class BrowserToolBase {
                 errorMsg.includes('Invalid selector') ||
                 errorMsg.includes('SyntaxError') ||
                 errorMsg.includes('selector')) {
+                const conciseMsg = this.sanitizeSelectorEngineMessage(errorMsg);
+                // Helpful, accurate guidance with Tailwind-style examples
+                const tips = [
+                    '💡 Tips:',
+                    '  • Tailwind arbitrary values need escaping in class selectors: .min-w-\\[300px\\]',
+                    '  • Colons in class names must be escaped: .dark\\:bg-gray-700',
+                    '  • Prefer robust selectors: use testid:name or [data-testid="..."]',
+                    '  • Attribute selectors avoid escaping issues: [class*="min-w-[300px]"]',
+                    '',
+                    'Examples:',
+                    '  ✓ .min-w-\\[300px\\] .flex-1',
+                    '  ✓ testid:submit-button',
+                    '  ✓ #login-form'
+                ].join('\n');
                 throw new Error(`Invalid CSS selector: "${selector}"\n\n` +
-                    `Selector syntax error: ${errorMsg}\n\n` +
-                    `💡 Tips:\n` +
-                    `  • CSS selectors don't need backslash escapes for [ ] or :\n` +
-                    `  • Use .class-name or #id without escaping\n` +
-                    `  • For data attributes, use [data-attr="value"]\n` +
-                    `  • For testid shortcuts, use testid:name\n\n` +
-                    `Examples:\n` +
-                    `  ✓ .dark:bg-gray-700\n` +
-                    `  ✓ .top-[36px]\n` +
-                    `  ✓ testid:submit-button\n` +
-                    `  ✓ #login-form\n` +
-                    `  ✗ .dark\\:bg-gray-700 (unnecessary escape)\n` +
-                    `  ✗ .top-\\[36px\\] (unnecessary escape)`);
+                    (conciseMsg ? `Selector syntax error: ${conciseMsg}\n\n` : '') +
+                    tips);
             }
             // Re-throw other errors as-is
             throw error;
@@ -248,12 +293,19 @@ export class BrowserToolBase {
      * @returns Formatted string or empty if only one element
      */
     formatElementSelectionInfo(selector, elementIndex, totalCount, preferredVisible = true) {
+        const usesNth = selector.includes('>> nth=');
         if (totalCount <= 1) {
+            // Even when a single element is ultimately targeted, discourage nth usage
+            // because it is brittle across layout/content changes.
+            if (usesNth) {
+                return "💡 Tip: Selector uses '>> nth='. Prefer adding a unique data-testid for robust selection.";
+            }
             return '';
         }
         const duplicateWarning = this.getDuplicateTestIdWarning(selector, totalCount).trimEnd();
         const nthHint = this.buildNthSelectorHint(selector, totalCount).trimEnd();
-        const extraHints = [duplicateWarning, nthHint].filter(Boolean).join('\n');
+        const avoidNth = usesNth ? "💡 Tip: Avoid relying on '>> nth='; add a unique data-testid instead." : '';
+        const extraHints = [duplicateWarning, nthHint, avoidNth].filter(Boolean).join('\n');
         const baseMessage = preferredVisible
             ? `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1} (first visible)`
             : `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1}`;
@@ -276,10 +328,14 @@ export class BrowserToolBase {
             selector.startsWith('data-cy:') ||
             selector.match(/^\[data-(testid|test|cy)=/);
         if (isTestIdSelector) {
-            return `💡 Tip: Test IDs should be unique. Consider making this test ID unique to avoid ambiguity.\n\n`;
+            return (`💡 Tip: Test IDs should be unique. Consider making this test ID unique to avoid ambiguity.\n` +
+                `   Primary fix: assign a unique data-testid to the intended element.\n` +
+                `   Workaround: if you cannot change markup, you may use '>> nth=<index>' temporarily.\n\n`);
         }
         // Suggest testid for non-testid selectors
-        return `💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.\n\n`;
+        return (`💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.\n` +
+            `   Primary fix: add data-testid and target it (e.g., testid:submit).\n` +
+            `   Workaround: use '>> nth=<index>' only when you can't add test IDs.\n\n`);
     }
     /**
      * Provide a hint for using >> nth= when multiple elements match a selector
@@ -295,6 +351,11 @@ export class BrowserToolBase {
         const firstExample = `${trimmed} >> nth=0`;
         const lastIndex = Math.max(totalCount - 1, 1);
         const lastExample = `${trimmed} >> nth=${lastIndex}`;
-        return `💡 Hint: Append ">> nth=<index>" to target a specific match.\n   Example: ${firstExample} (first match)\n   Or: ${lastExample} (last match)`;
+        return (`Primary fix: add a unique data-testid to the intended element and select it directly.\n` +
+            `Workaround: Append ">> nth=<index>" to target a specific match when you cannot change markup.\n` +
+            `   Example: ${firstExample} (first match)\n` +
+            `   Or: ${lastExample} (last match)\n` +
+            `Note: nth selectors are brittle and may break with layout/content changes.\n` +
+            `Prefer unique data-testid attributes for long-term stability.`);
     }
 }

package/dist/tools/browser/console/__tests__/console.test.js

@@ -195,4 +195,46 @@ describe('GetConsoleLogsTool', () => {
         // (The truncation happens in toolHandler.ts before calling registerConsoleMessage)
         expect(logsText).toContain(longStackError);
     });
+    test('raw format preview should include confirm token and confirmation returns full payload', async () => {
+        // Generate enough long logs to exceed preview threshold
+        for (let i = 0; i < 40; i++) {
+            consoleLogsTool.registerConsoleMessage('log', `RAW-LONG-${i} ` + 'X'.repeat(160));
+        }
+        const previewResult = await consoleLogsTool.execute({ format: 'raw' }, mockContext);
+        expect(previewResult.isError).toBe(false);
+        const previewText = previewResult.content.map(c => c.text).join('\n');
+        // Should include confirm_output token reference
+        expect(previewText).toMatch(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        const token = (previewText.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        // Confirm to retrieve full payload
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const full = await confirmTool.execute({ token }, mockContext);
+        expect(full.isError).toBe(false);
+        const fullText = full.content.map(c => c.text).join('\n');
+        // By default limit=20 → header should reflect 20 lines
+        expect(fullText).toContain('Retrieved 20 console log(s):');
+        // And include one of our long messages
+        expect(fullText).toContain('RAW-LONG-39');
+    });
+    test('grouped format preview should include confirm token and confirmation returns full payload', async () => {
+        // Generate 30 unique messages to form distinct groups and exceed threshold
+        for (let i = 0; i < 30; i++) {
+            consoleLogsTool.registerConsoleMessage('log', `GROUP-LONG-${i} ` + 'G'.repeat(160));
+        }
+        const previewResult = await consoleLogsTool.execute({}, mockContext); // grouped is default
+        expect(previewResult.isError).toBe(false);
+        const previewText = previewResult.content.map(c => c.text).join('\n');
+        expect(previewText).toMatch(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        const token = (previewText.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const full = await confirmTool.execute({ token }, mockContext);
+        expect(full.isError).toBe(false);
+        const fullText = full.content.map(c => c.text).join('\n');
+        // Header reflects number of groups shown (limit default 20)
+        expect(fullText).toContain('Retrieved 20 console log(s):');
+        // Should include one of the first 20 grouped messages
+        expect(fullText).toContain('GROUP-LONG-0');
+    });
 });

package/dist/tools/browser/console/get_console_logs.d.ts

@@ -8,7 +8,6 @@ export declare class GetConsoleLogsTool extends BrowserToolBase {
     private lastCallTimestamp;
     private lastNavigationTimestamp;
     private lastInteractionTimestamp;
-    private confirmTokens;
     static latestInstance: GetConsoleLogsTool | null;
     constructor(server: any);
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;

package/dist/tools/browser/console/get_console_logs.js

@@ -1,5 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse } from '../../common/types.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 /**
  * Tool for retrieving and filtering console logs from the browser
  */
@@ -11,13 +12,12 @@ export class GetConsoleLogsTool extends BrowserToolBase {
         this.lastCallTimestamp = 0;
         this.lastNavigationTimestamp = 0;
         this.lastInteractionTimestamp = 0;
-        this.confirmTokens = new Map();
         GetConsoleLogsTool.latestInstance = this;
     }
     static getMetadata(sessionConfig) {
         return {
             name: "get_console_logs",
-            description: "Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and require confirmToken to fetch the full payload.",
+            description: "Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -44,10 +44,6 @@ export class GetConsoleLogsTool extends BrowserToolBase {
                         description: "Output format: 'grouped' (default, deduped with counts) or 'raw' (chronological, ungrouped)",
                         enum: ["grouped", "raw"]
                     },
-                    confirmToken: {
-                        type: "string",
-                        description: "One-time token to return large outputs. Obtain it by calling without confirmToken to receive a preview."
-                    }
                 },
                 required: [],
             },
@@ -121,27 +117,17 @@ export class GetConsoleLogsTool extends BrowserToolBase {
             // Guard large outputs by character size
             const header = `Retrieved ${messages.length} console log(s):`;
             const textPayload = [header, ...messages].join('\n');
-            const tokenKey = `raw:${sinceArg}:${args.type || 'all'}:${args.search || ''}:${limit}:${messages.length}`;
             if (textPayload.length >= PREVIEW_THRESHOLD) {
-                const expected = this.confirmTokens.get(tokenKey);
-                const provided = args.confirmToken;
-                if (!provided || !expected || provided !== expected) {
-                    const newToken = Math.random().toString(36).slice(2, 10);
-                    this.confirmTokens.set(tokenKey, newToken);
-                    const previewLines = messages.slice(0, Math.min(messages.length, 10));
-                    const preview = [
-                        `Matched ${logs.length} log(s). Showing ${previewLines.length} line(s) preview.`,
-                        ...previewLines,
-                        '',
-                        `Output is large (~${Math.round(textPayload.length / 3)} tokens). To fetch full content, call again with confirmToken: "${newToken}"`,
-                        'Tip: refine with search/type/since/limit or prefer grouped format.'
-                    ].join('\n');
-                    return createSuccessResponse(preview);
-                }
-                else {
-                    // One-time token — consume and proceed
-                    this.confirmTokens.delete(tokenKey);
-                }
+                const previewLines = [
+                    `Matched ${logs.length} log(s). Showing ${Math.min(messages.length, 10)} line(s) preview.`,
+                    ...messages.slice(0, Math.min(messages.length, 10)),
+                ];
+                const preview = makeConfirmPreview(() => textPayload, {
+                    counts: { totalLength: textPayload.length, shownLength: previewLines.join('\n').length, totalMatched: logs.length, shownCount: Math.min(messages.length, 10), truncated: true },
+                    previewLines,
+                    extraTips: ['Tip: refine with search/type/since/limit or prefer grouped format.'],
+                });
+                return createSuccessResponse(preview.lines.join('\n'));
             }
             return createSuccessResponse([header, ...messages]);
         }
@@ -172,25 +158,17 @@ export class GetConsoleLogsTool extends BrowserToolBase {
         }
         // Guard large grouped outputs
         const textPayload = lines.join('\n');
-        const tokenKey = `grouped:${sinceArg}:${args.type || 'all'}:${args.search || ''}:${limit}:${groups.size}`;
         if (textPayload.length >= PREVIEW_THRESHOLD) {
-            const expected = this.confirmTokens.get(tokenKey);
-            const provided = args.confirmToken;
-            if (!provided || !expected || provided !== expected) {
-                const newToken = Math.random().toString(36).slice(2, 10);
-                this.confirmTokens.set(tokenKey, newToken);
-                const previewBody = [
-                    `Matched ${groups.size} group(s). Showing ${limitedGroups.length}.`,
-                    ...lines.slice(0, Math.min(lines.length, 12)),
-                    '',
-                    `Output is large (~${Math.round(textPayload.length / 3)} tokens). To fetch full content, call again with confirmToken: "${newToken}"`,
-                    'Tip: refine with search/type/since/limit.'
-                ].join('\n');
-                return createSuccessResponse(previewBody);
-            }
-            else {
-                this.confirmTokens.delete(tokenKey);
-            }
+            const previewLines = [
+                `Matched ${groups.size} group(s). Showing ${limitedGroups.length}.`,
+                ...lines.slice(0, Math.min(lines.length, 12)),
+            ];
+            const preview = makeConfirmPreview(() => textPayload, {
+                counts: { totalLength: textPayload.length, shownLength: previewLines.join('\n').length, totalMatched: groups.size, shownCount: limitedGroups.length, truncated: true },
+                previewLines,
+                extraTips: ['Tip: refine with search/type/since/limit.'],
+            });
+            return createSuccessResponse(preview.lines.join('\n'));
         }
         return createSuccessResponse(lines);
     }