@yusufffararatt/dombridge-mcp 2.7.5

package/src/tools/quick-scan.js

@@ -0,0 +1,418 @@
+/**
+ * Tool: quick_scan
+ * Profile-first bootstrap for agent workflows.
+ *
+ * Phase 2.4: Refactored from (args, extensionData, httpPort) to (args, bridgeClient).
+ * All state reads go through bridgeClient property getters.
+ * All request/result operations go through bridgeClient.queueRequest/waitForResult.
+ */
+
+import { loadProfile, extractDomain } from '../profiles/profile-manager.js';
+import { markProfileChecked, markProfileLoaded, touchTabField, isFieldFresh } from '../utils/workflow-state.js';
+import { enrichProfile } from '../profiles/profile-enricher.js';
+
+async function callAnalyzePage(bridgeClient, tabId) {
+    const { analyzePageTool } = await import('./analyze-page.js');
+    return analyzePageTool.handler({ includeApis: true, verbose: false, tabId }, bridgeClient);
+}
+
+async function callGetTabs(bridgeClient) {
+    const requestId = `tabs-quick-scan-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+    try {
+        await bridgeClient.queueRequest('tabs', { id: requestId });
+        const result = await bridgeClient.waitForResult('tabs', requestId, 3000);
+        if (result && result.tabs) {
+            return result.tabs;
+        }
+    } catch {
+        // Non-critical — tab resolution is best-effort
+    }
+
+    return [];
+}
+
+async function callExtractData(bridgeClient, tabId) {
+    const { extractDataTool } = await import('./extract-data.js');
+    return extractDataTool.handler({ verbose: false, tabId }, bridgeClient);
+}
+
+async function callDiscoverApis(bridgeClient, tabId) {
+    const { discoverApisTool } = await import('./discover-apis.js');
+    return discoverApisTool.handler({ limit: 5, force: true, tabId }, bridgeClient);
+}
+
+async function callCheckSiteChanges(bridgeClient, domain) {
+    // Bug #5 fix: check_site_changes was merged into manage_site_profile (unified profile tool)
+    const { manageSiteProfileTool } = await import('./manage-site-profile.js');
+    return manageSiteProfileTool.handler({ action: 'check', domain }, bridgeClient);
+}
+
+async function callCaptureScreenshot(bridgeClient, tabId) {
+    const { captureScreenshotTool } = await import('./screenshot_tools.js');
+    return captureScreenshotTool.handler({ tabId }, bridgeClient);
+}
+
+function textOf(mcpResult) {
+    return mcpResult?.content?.[0]?.text || '';
+}
+
+function domainFromAnalyzeText(analyzeText) {
+    const urlLine = analyzeText.split('\n').find((line) => line.startsWith('URL: '));
+    if (!urlLine) return '';
+    try {
+        return extractDomain(urlLine.replace(/^URL:\s*/, '').trim());
+    } catch {
+        return '';
+    }
+}
+
+function domainFromExtension(bridgeClient) {
+    try {
+        const url = bridgeClient.activeTabUrl
+            || bridgeClient.selectedElement?.sessionInfo?.url
+            || bridgeClient.selectedElement?.pageUrl
+            || '';
+        return extractDomain(url);
+    } catch {
+        return '';
+    }
+}
+
+function summarize(text, lines = 3) {
+    return text
+        .split('\n')
+        .filter((line) => line.trim())
+        .slice(0, lines)
+        .join('\n');
+}
+
+function getProfilePageType(profile) {
+    return profile?.pageCharacteristics?.type || 'unknown';
+}
+
+function buildProfileCoverage(profile) {
+    if (!profile) return [];
+
+    const coverage = [];
+    if (profile.framework?.length) coverage.push(`framework=${profile.framework.join(', ')}`);
+    if (profile.dataSchema?.sources?.length) coverage.push(`${profile.dataSchema.sources.length} data source(s)`);
+    if (profile.apiEndpoints?.length) coverage.push(`${profile.apiEndpoints.length} endpoint(s)`);
+    if (profile.knownPaths?.length) coverage.push(`${profile.knownPaths.length} extraction path(s)`);
+    return coverage;
+}
+
+function getDiscoveryMode({ usedProfile, ranAnalyze, ranExtract, ranDiscover }) {
+    if (usedProfile && !ranAnalyze && !ranExtract && !ranDiscover) return 'Profile-only';
+    if (usedProfile && (ranAnalyze || ranExtract || ranDiscover)) return 'Profile + selective refresh';
+    return 'Live discovery';
+}
+
+function buildInteractionHints(sourceText, intent, profile, { ranAnalyze = false, ranExtract = false, ranDiscover = false } = {}) {
+    const hints = [];
+    const lower = `${sourceText || ''}\n${intent || ''}`.toLowerCase();
+
+    if (/forms.*[1-9]/.test(lower) || (profile?.pageCharacteristics?.forms ?? 0) > 0) {
+        hints.push('Form detected - `execute_action` can fill and submit it');
+    }
+    if (/inputs.*[1-9]/.test(lower) || (profile?.pageCharacteristics?.inputs ?? 0) > 0) {
+        hints.push('Input fields detected - use `execute_action({ actionType: "type", ... })`');
+    }
+    if (/paginat|next.*page|load more/i.test(lower) || profile?.paginationPatterns?.type) {
+        hints.push('Pagination signal - consider `paginate` for list/archive extraction');
+    }
+    if (/button.*[1-9]/.test(lower) || (profile?.pageCharacteristics?.buttons ?? 0) > 0) {
+        hints.push('Buttons detected - `execute_action({ actionType: "click", ... })` can trigger interactions');
+    }
+    if (/login|sign.?in|auth|cookie|session|password/i.test(lower) || profile?.authInfo?.type) {
+        hints.push('Auth-required page detected - call `export_session()` to capture cookies/tokens for Playwright handoff');
+    }
+    if (!profile && (ranAnalyze || ranExtract || ranDiscover)) {
+        hints.push('No profile saved for this site - call `manage_site_profile({ action: "save" })` after discovery to persist findings');
+    }
+
+    return hints;
+}
+
+/**
+ * Resolves target tab in a single fetch, returning both tabId and tabUrl.
+ * Single fetch avoids a second tabs request (which times out if extension just responded).
+ */
+async function resolveTargetTab(bridgeClient, argTabId, tabUrl) {
+    if (!tabUrl && argTabId === undefined) return { tabId: undefined, tabUrl: '' };
+
+    const tabs = await callGetTabs(bridgeClient);
+
+    if (argTabId !== undefined) {
+        const match = tabs.find((t) => t.id === argTabId);
+        return { tabId: argTabId, tabUrl: match?.url || '' };
+    }
+
+    const needle = tabUrl.toLowerCase();
+    const match = tabs.find((tab) => typeof tab.url === 'string' && tab.url.toLowerCase().includes(needle));
+    return match ? { tabId: match.id, tabUrl: match.url } : { tabId: undefined, tabUrl: '' };
+}
+
+export const quickScanTool = {
+    name: 'quick_scan',
+    description: `One-call context bootstrap — analyze + profile check + discovery in one step.
+
+WORKFLOW POSITION: First Step — use before get_element / get_network_trace
+
+WHAT IT DOES:
+1. Resolves target tab/domain
+2. Loads saved profile (or runs live discovery if stale)
+3. Refreshes only stale or missing fields
+4. Returns concise summary of profile vs live data
+
+WHAT IT DOES NOT DO:
+- Does NOT select elements or run network trace
+- Does NOT click, type, scroll, or paginate
+- Does NOT print screenshot binary
+
+PARAMETERS:
+- tabUrl (optional): Match tab by URL substring
+- tabId (optional): Target specific tab by ID
+- intent (optional): What you want (e.g. "extract product prices")
+- verbose (optional): Return full detail instead of summary
+- refreshProfile (optional): Force drift check with manage_site_profile({action:"check"})
+- preferLive (optional): Ignore saved profile, run live discovery
+
+EXAMPLE:
+quick_scan({ tabUrl: "trendyol.com", intent: "extract prices" })
+quick_scan({ tabId: 142, preferLive: true })`,
+
+    inputSchema: {
+        type: 'object',
+        properties: {
+            tabUrl: {
+                type: 'string',
+                description: 'URL substring to target a specific tab (e.g. "trendyol.com", "sofascore").'
+            },
+            intent: {
+                type: 'string',
+                description: 'What you want to do (e.g. "extract product prices", "find pagination API")'
+            },
+            verbose: {
+                type: 'boolean',
+                description: 'Return full detail from analyze/discovery subtools (default: false)',
+                default: false
+            },
+            refreshProfile: {
+                type: 'boolean',
+                description: 'Force a live drift check with manage_site_profile({action:"check"}) (default: false)',
+                default: false
+            },
+            preferLive: {
+                type: 'boolean',
+                description: 'Bypass profile freshness and run live discovery (default: false)',
+                default: false
+            },
+            tabId: {
+                type: 'number',
+                description: 'Target a specific tab by ID (from debug_mcp_state).'
+            }
+        }
+    },
+
+    handler: async (args, bridgeClient) => {
+        const { tabUrl, tabId: argTabId, intent = '', verbose = false, refreshProfile = false, preferLive = false } = args || {};
+
+        if (!bridgeClient.isConnected) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: 'Error: Extension not connected.\n\nREQUIRED:\n1. Reload the webpage\n2. Ensure the Chrome extension is active'
+                }],
+                isError: true
+            };
+        }
+
+        const { tabId, tabUrl: resolvedTabUrl } = await resolveTargetTab(bridgeClient, argTabId, tabUrl);
+        if (tabUrl && tabId === undefined) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: `Error: No open tab matched "${tabUrl}". Use \`debug_mcp_state()\` to inspect available tabs or pass \`tabId\` directly.`
+                }],
+                isError: true
+            };
+        }
+
+        if (tabId !== undefined) touchTabField(tabId, 'lastQuickScanAt');
+
+        let domain = (resolvedTabUrl ? extractDomain(resolvedTabUrl) : '') || domainFromExtension(bridgeClient);
+        let profile = domain && !preferLive ? loadProfile(domain) : null;
+        let analyzeText = '';
+        const sections = [];
+
+        const needAnalyze = preferLive || !domain || !profile || !isFieldFresh(domain, 'framework') || !isFieldFresh(domain, 'pageCharacteristics');
+        let ranAnalyze = false;
+        let ranExtract = false;
+        let ranDiscover = false;
+        let cspBlocked = false;
+        let usedProfile = Boolean(profile) && !preferLive;
+
+        if (needAnalyze) {
+            try {
+                const analyzeResult = await callAnalyzePage(bridgeClient, tabId);
+                analyzeText = textOf(analyzeResult);
+                domain = domainFromAnalyzeText(analyzeText) || domain;
+                sections.push({ label: 'Page Analysis', text: analyzeText, origin: 'live' });
+                ranAnalyze = true;
+                if (tabId !== undefined) touchTabField(tabId, 'lastAnalyzeAt');
+                if (domain && !preferLive) {
+                    profile = loadProfile(domain);
+                    usedProfile = Boolean(profile);
+                }
+            } catch (e) {
+                sections.push({ label: 'Page Analysis', text: `Analysis failed: ${e.message}`, origin: 'live' });
+            }
+        } else if (profile) {
+            sections.push({
+                label: 'Page Analysis',
+                text: `Using saved analysis for ${domain}: frameworks=${profile.framework?.join(', ') || 'unknown'}, pageType=${getProfilePageType(profile)}`,
+                origin: 'profile'
+            });
+        }
+
+        if (profile) {
+            const coverage = buildProfileCoverage(profile).join(', ');
+            sections.push({
+                label: 'Profile Status',
+                text: `Saved profile found for ${domain} (v${profile.version}). Coverage: ${coverage || 'basic metadata only'}.`,
+                origin: 'profile'
+            });
+            markProfileLoaded(domain);
+        }
+
+        if (profile && refreshProfile) {
+            try {
+                const changeResult = await callCheckSiteChanges(bridgeClient, domain);
+                sections.push({ label: 'Drift Check', text: textOf(changeResult), origin: 'live' });
+                markProfileChecked(domain);
+            } catch (e) {
+                sections.push({ label: 'Drift Check', text: `Profile check failed: ${e.message}`, origin: 'live' });
+            }
+        }
+
+        const pageType = ranAnalyze
+            ? (/SSR \(|API-driven/i.test(analyzeText) ? (/SSR \(/.test(analyzeText) ? 'SSR' : 'SPA') : getProfilePageType(profile))
+            : getProfilePageType(profile);
+
+        const needExtract = preferLive || !profile || !isFieldFresh(domain, 'dataSchema') || !isFieldFresh(domain, 'knownPaths');
+        const needDiscover = preferLive || !profile || !isFieldFresh(domain, 'apiEndpoints');
+
+        if (needExtract && (pageType === 'SSR' || pageType === 'unknown')) {
+            try {
+                const extractResult = await callExtractData(bridgeClient, tabId);
+                sections.push({ label: 'Embedded Data', text: textOf(extractResult), origin: 'live' });
+                ranExtract = true;
+            } catch (e) {
+                sections.push({ label: 'Embedded Data', text: `extract_data failed: ${e.message}`, origin: 'live' });
+                if (e.message?.includes('CSP') || e.message?.includes('unsafe-eval')) cspBlocked = true;
+            }
+        } else if (profile?.dataSchema?.sources?.length) {
+            sections.push({
+                label: 'Embedded Data',
+                text: `Using ${profile.dataSchema.sources.length} saved source(s); primary=${profile.dataSchema.sources.slice(0, 3).map((source) => source.key).join(', ')}`,
+                origin: 'profile'
+            });
+        }
+
+        if (needDiscover && (pageType === 'SPA' || pageType === 'unknown' || preferLive)) {
+            try {
+                const discoverResult = await callDiscoverApis(bridgeClient, tabId);
+                sections.push({ label: 'API Discovery', text: textOf(discoverResult), origin: 'live' });
+                ranDiscover = true;
+                if (tabId !== undefined) touchTabField(tabId, 'lastDiscoverApisAt');
+            } catch (e) {
+                sections.push({ label: 'API Discovery', text: `discover_apis failed: ${e.message}`, origin: 'live' });
+            }
+        } else if (profile?.apiEndpoints?.length) {
+            sections.push({
+                label: 'API Discovery',
+                text: `Using ${profile.apiEndpoints.length} saved endpoint(s); top=${profile.apiEndpoints.slice(0, 3).map((endpoint) => `${endpoint.method} ${endpoint.url}`).join(' | ')}`,
+                origin: 'profile'
+            });
+        }
+
+        if (!ranAnalyze && !ranExtract && !ranDiscover && !profile) {
+            try {
+                await callCaptureScreenshot(bridgeClient, tabId);
+                sections.push({
+                    label: 'Visual Fallback',
+                    text: 'No profile and no live discovery signals available. Screenshot captured; call `capture_screenshot()` to inspect the page visually.',
+                    origin: 'live'
+                });
+            } catch {
+                // Non-fatal.
+            }
+        }
+
+        profile = domain ? loadProfile(domain) : profile;
+        const hints = buildInteractionHints(analyzeText, intent, profile, { ranAnalyze, ranExtract, ranDiscover });
+        const discoveryMode = getDiscoveryMode({ usedProfile, ranAnalyze, ranExtract, ranDiscover });
+        const lines = ['## quick_scan', ''];
+
+        if (domain) lines.push(`**Site:** ${domain}`);
+        if (tabId !== undefined) lines.push(`**Tab ID:** ${tabId}`);
+        if (tabUrl) lines.push(`**Tab match:** ${tabUrl}`);
+        if (intent) lines.push(`**Intent:** ${intent}`);
+        lines.push(`**Discovery mode:** ${discoveryMode}`);
+        lines.push('');
+
+        if (profile) {
+            lines.push(`**Profile freshness:** framework=${isFieldFresh(domain, 'framework') ? 'fresh' : 'stale'}, dataSchema=${isFieldFresh(domain, 'dataSchema') ? 'fresh' : 'stale'}, apiEndpoints=${isFieldFresh(domain, 'apiEndpoints') ? 'fresh' : 'stale'}`);
+            lines.push('');
+        }
+
+        for (const section of sections) {
+            if (!section.text || section.text.trim() === '') continue;
+            const prefix = section.origin === 'profile' ? '[profile]' : '[live]';
+            if (verbose) {
+                lines.push(`### ${section.label} ${prefix}`);
+                lines.push(section.text.trim());
+                lines.push('');
+            } else {
+                lines.push(`**${section.label} ${prefix}:** ${summarize(section.text, 3)}`);
+                lines.push('');
+            }
+        }
+
+        if (profile?.autoNotes?.length) {
+            lines.push('### Profile Highlights');
+            profile.autoNotes.slice(-4).forEach((entry) => {
+                lines.push(`- [${entry.source}] ${entry.text}`);
+            });
+            lines.push('');
+        }
+
+        if (hints.length > 0) {
+            lines.push('### Interaction Hints');
+            hints.forEach((hint) => lines.push(`- ${hint}`));
+            lines.push('');
+        }
+
+        // CSP detection: save to profile + show warning
+        const profileCsp = profile?.cspStatus === 'strict';
+        if (cspBlocked && domain) {
+            enrichProfile(domain, 'csp_detection', { level: 'strict' });
+        }
+
+        lines.push('---');
+        lines.push('**Next steps:**');
+        if (cspBlocked || profileCsp) {
+            lines.push(`- ⚠️ **CSP strict site** — \`execute_js\` auto-bypasses CSP (tab reloads once). \`discover_apis()\` works without CSP.`);
+        }
+        if (profile) lines.push(`- \`manage_site_profile({ action: "load", domain: "${domain}" })\` -> inspect the full site dossier`);
+        if (profile && (ranAnalyze || ranExtract || ranDiscover)) lines.push(`- \`manage_site_profile({ action: "save", domain: "${domain}" })\` -> update profile with fresh live data`);
+        lines.push('- `get_element({ css: "SELECTOR" })` -> target the exact field you want to scrape');
+        lines.push('- `get_network_trace()` -> connect a DOM value to its API response when needed');
+        if (profile && !refreshProfile) lines.push(`- \`manage_site_profile({ action: "check", domain: "${domain}" })\` -> verify drift before long scraping runs`);
+
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }]
+        };
+    }
+};

package/src/tools/screenshot_tools.js

@@ -0,0 +1,117 @@
+/**
+ * Screenshot Tool for Visual Feedback
+ * Ajanın sayfanın görünür alanının (viewport) ekran görüntüsünü almasını sağlar
+ *
+ * Phase 2.4: Refactored from (args, extensionData, httpPort) to (args, bridgeClient).
+ */
+
+export const captureScreenshotTool = {
+    name: 'capture_screenshot',
+    description: `This is a tool from the dombridge MCP server.
+Take a screenshot of a Chrome tab's visible area (viewport).
+
+WORKFLOW POSITION: 🔧 Visual Feedback - Use when actions fail or visual confirmation is needed
+
+PREREQUISITES:
+- ✅ Extension must be connected
+
+FEATURES:
+- Returns a Base64 encoded JPEG image data URL of the current visible screen.
+- High performance (JPEG, 80% quality) limits size to ~1MB.
+- Best used to verify if UI has changed or why elements can't be interacted with.
+
+MULTI-TAB: Call debug_mcp_state() first to get tab IDs, then pass tabId to screenshot a specific tab.
+
+Use this tool if execute_action fails multiple times or if you need to visually check the page state.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            tabId: {
+                type: 'number',
+                description: 'Target tab ID (optional). Omit to use active tab. Get IDs from debug_mcp_state().'
+            }
+        },
+        required: []
+    },
+    handler: async (args, bridgeClient) => {
+        if (!bridgeClient.isConnected) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Error: Extension not connected.\n\nREQUIRED STEPS:\n1. Ensure Chrome extension is active\n2. Reload target page`
+                    }
+                ],
+                isError: true
+            };
+        }
+
+        const { tabId } = args || {};
+        const requestId = `screenshot-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+        try {
+            // Send request via bridge daemon
+            await bridgeClient.queueRequest('capture-screenshot', {
+                id: requestId,
+                ...(tabId ? { tabId } : {})
+            });
+
+            // Wait for extension to process and return result
+            const timeout = 15000; // Screenshots may take longer
+            const resultItem = await bridgeClient.waitForResult('capture-screenshot', requestId, timeout + 3000);
+
+            if (resultItem) {
+                if (resultItem.error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `❌ Screenshot Error: ${resultItem.error}\n\nREQUIRED STEPS:\n1. Check page compatibility and permissions`
+                            }
+                        ],
+                        isError: true
+                    };
+                }
+
+                // MCP SDK protocol format: flat data + mimeType fields
+                const base64Data = resultItem.dataUrl.split(',')[1];
+                const mimeType = resultItem.dataUrl.substring(resultItem.dataUrl.indexOf(':') + 1, resultItem.dataUrl.indexOf(';')) || 'image/jpeg';
+
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Screenshot captured successfully. Here is the visual context:`
+                        },
+                        {
+                            type: 'image',
+                            data: base64Data,
+                            mimeType: mimeType
+                        }
+                    ]
+                };
+            }
+
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Action Timeout: The extension did not report back within ${timeout}ms.`
+                    }
+                ],
+                isError: true
+            };
+
+        } catch (e) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Server Error: ${e.message}\n\nREQUIRED STEPS:\n1. Check daemon status\n2. Reconnect extension`
+                    }
+                ],
+                isError: true
+            };
+        }
+    }
+};

package/src/utils/circuit-breaker.js

@@ -0,0 +1,112 @@
+/**
+ * Circuit Breaker Utility
+ * Extension tool çağrılarını hata durumunda korur.
+ *
+ * States:
+ *   CLOSED    — normal, requests pass through
+ *   OPEN      — 3 consecutive failures → requests rejected immediately
+ *   HALF_OPEN — after 30s cooldown, 1 probe request allowed
+ */
+
+const FAILURE_THRESHOLD = 3;
+const RECOVERY_TIMEOUT_MS = 30000;
+
+export class CircuitBreaker {
+  constructor(name) {
+    this.name = name;
+    this.state = 'CLOSED';
+    this.failures = 0;
+    this.lastFailureTime = null;
+    this.probePending = false;
+  }
+
+  /**
+   * Execute a function through the circuit breaker.
+   * @param {Function} fn — async function to execute
+   * @returns {Promise<any>} result of fn, or throws if circuit is OPEN
+   */
+  async execute(fn) {
+    if (this.state === 'OPEN') {
+      const elapsed = Date.now() - this.lastFailureTime;
+      if (elapsed >= RECOVERY_TIMEOUT_MS) {
+        this.state = 'HALF_OPEN';
+        this.probePending = false;
+      } else {
+        const remaining = Math.ceil((RECOVERY_TIMEOUT_MS - elapsed) / 1000);
+        throw new Error(
+          `Circuit breaker OPEN for "${this.name}". Retry in ${remaining}s.`
+        );
+      }
+    }
+
+    if (this.state === 'HALF_OPEN') {
+      if (this.probePending) {
+        throw new Error(
+          `Circuit breaker HALF_OPEN for "${this.name}". Probe in progress, retry shortly.`
+        );
+      }
+      this.probePending = true;
+    }
+
+    try {
+      const result = await fn();
+      this._onSuccess();
+      return result;
+    } catch (err) {
+      this._onFailure();
+      throw err;
+    }
+  }
+
+  _onSuccess() {
+    this.failures = 0;
+    this.state = 'CLOSED';
+    this.probePending = false;
+  }
+
+  _onFailure() {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+    this.probePending = false;
+    if (this.failures >= FAILURE_THRESHOLD) {
+      this.state = 'OPEN';
+    }
+  }
+
+  getStatus() {
+    return {
+      name: this.name,
+      state: this.state,
+      failures: this.failures,
+      lastFailureTime: this.lastFailureTime
+    };
+  }
+
+  reset() {
+    this.state = 'CLOSED';
+    this.failures = 0;
+    this.lastFailureTime = null;
+  }
+}
+
+/**
+ * Pre-created circuit breakers for each tool type
+ */
+export const circuitBreakers = {
+  executeJs: new CircuitBreaker('execute_js'),
+  executeAction: new CircuitBreaker('execute_action'),
+  captureScreenshot: new CircuitBreaker('capture_screenshot'),
+  discoverApis: new CircuitBreaker('discover_apis'),
+  selectElement: new CircuitBreaker('select_element')
+};
+
+/**
+ * Reset all circuit breakers to CLOSED state.
+ * Called when extension reconnects after a disconnect — breakers that tripped
+ * during the disconnected period should not penalize the newly connected extension.
+ */
+export function resetAllCircuitBreakers() {
+  for (const cb of Object.values(circuitBreakers)) {
+    cb.reset();
+  }
+}

package/src/utils/extract-density.js

@@ -0,0 +1,21 @@
+export function computeSourceDensity(source) {
+  const leafCount = (source.leafPaths || []).length;
+  const topKeyCount = Object.keys(source.schema || {}).filter(k => !k.startsWith('__')).length;
+
+  if (leafCount <= 1 && topKeyCount <= 1) return 'noise';
+  if (leafCount >= 20) return 'rich';
+  return 'normal';
+}
+
+export function filterNoiseSources(sources) {
+  if (sources.length <= 5) return sources;
+
+  const annotated = sources.map((s) => ({ source: s, density: computeSourceDensity(s) }));
+  const noiseCount = annotated.filter(a => a.density === 'noise').length;
+
+  // Only filter noise if >50% of sources are noise AND there are >5 sources
+  if (noiseCount > sources.length / 2) {
+    return annotated.filter(a => a.density !== 'noise').map(a => a.source);
+  }
+  return sources;
+}