feat(inspect): add opt-in output token metrics (#981)

src/tools/inspect.ts

@@ -14,6 +14,7 @@ import { TOOL_ANNOTATIONS } from '../types/tool-annotations';
 import { getSessionManager } from '../session-manager';
 import { withTimeout } from '../utils/with-timeout';
 import { getAllShadowRoots, querySelectorInShadowRoots } from '../utils/shadow-dom';
+import { appendMetricsFooter, buildTextMetrics } from '../core/metrics/token-estimate';
 import {
   formatNodeRefToken,
   getCurrentLoaderId,
@@ -39,6 +40,10 @@ const definition: MCPToolDefinition = {
         enum: ['interactive', 'all', 'visible'],
         description: 'Element scope. Default: visible',
       },
+      include_metrics: {
+        type: 'boolean',
+        description: 'When true, append approximate returned size/token metrics to text output. Default: false.',
+      },
     },
     required: ['tabId', 'query'],
   },
@@ -107,6 +112,7 @@ const handler: ToolHandler = async (
   const tabId = args.tabId as string;
   const query = args.query as string;
   const scope = (args.scope as string) || 'visible';
+  const includeMetrics = args.include_metrics === true;
 
   const sessionManager = getSessionManager();
 
@@ -577,9 +583,15 @@ const handler: ToolHandler = async (
 
     // Footer with page context (always included)
     lines.push(`[Page] ${inspectResult.url} | "${inspectResult.title}"`);
+    const text = lines.join('\n');
 
     return {
-      content: [{ type: 'text', text: lines.join('\n') }],
+      content: [{
+        type: 'text',
+        text: includeMetrics
+          ? appendMetricsFooter(text, buildTextMetrics(text, { mode: `inspect:${scope}` }))
+          : text,
+      }],
     };
   } catch (error) {
     return {