@sovovs/bycli 1.8.0 → 2.1.0

package/cli-manifest.json

@@ -14863,67 +14863,6 @@
     "modulePath": "jira/search.js",
     "sourceFile": "jira/search.js"
   },
-  {
-    "site": "juejin",
-    "name": "search",
-    "description": "掘金搜索",
-    "access": "read",
-    "domain": "juejin.cn",
-    "strategy": "public",
-    "browser": true,
-    "args": [
-      {
-        "name": "query",
-        "type": "str",
-        "required": true,
-        "positional": true,
-        "help": "搜索关键词"
-      },
-      {
-        "name": "limit",
-        "type": "int",
-        "default": 10,
-        "required": false,
-        "help": "返回结果数量 (max 20)"
-      },
-      {
-        "name": "type",
-        "type": "int",
-        "default": 0,
-        "required": false,
-        "help": "搜索类型：0=综合搜索，2=文章搜索，12=课程搜索，9=标签搜索，1=用户搜索",
-        "choices": [
-          "0",
-          "2",
-          "12",
-          "9",
-          "1"
-        ]
-      },
-      {
-        "name": "sort",
-        "type": "int",
-        "default": 0,
-        "required": false,
-        "help": "排序类型：0=综合排序，1=最新优先，2=最热优先",
-        "choices": [
-          "0",
-          "1",
-          "2"
-        ]
-      }
-    ],
-    "columns": [
-      "rank",
-      "title",
-      "author",
-      "summary",
-      "url"
-    ],
-    "type": "js",
-    "modulePath": "juejin/search.js",
-    "sourceFile": "juejin/search.js"
-  },
   {
     "site": "ke",
     "name": "chengjiao",

package/clis/twitter/search.js

@@ -268,10 +268,10 @@ cli({
     args: [
         { name: 'query', type: 'string', required: true, positional: true, help: 'Search query. Raw X operators (e.g. "exact phrase", #tag, OR, lang:en, since:YYYY-MM-DD, from:, since:) are passed through unchanged.' },
         { name: 'filter', type: 'string', default: 'top', choices: ['top', 'live'], help: 'Legacy alias for --product. Kept for backwards compatibility; if --product is set it wins.' },
-        { name: 'product', type: 'string', choices: PRODUCT_CHOICES, help: 'Which X search tab to read: top (default), live (Latest), photos, videos. Maps to the f= URL param.' },
+        { name: 'product', type: 'string', choices: [...PRODUCT_CHOICES], help: 'Which X search tab to read: top (default), live (Latest), photos, videos. Maps to the f= URL param.' },
         { name: 'from', type: 'string', help: 'Restrict to tweets authored by <user>. Leading @ is stripped. Equivalent to appending `from:<user>` to the query.' },
-        { name: 'has', type: 'string', choices: HAS_CHOICES, help: 'Restrict to tweets that have media|images|videos|links|replies. Maps to X\'s `filter:<has>` operator.' },
-        { name: 'exclude', type: 'string', choices: EXCLUDE_CHOICES, help: 'Exclude tweets matching <type>: replies|retweets|media|links. Maps to X\'s `-filter:<x>` operator (retweets → -filter:nativeretweets).' },
+        { name: 'has', type: 'string', choices: [...HAS_CHOICES], help: 'Restrict to tweets that have media|images|videos|links|replies. Maps to X\'s `filter:<has>` operator.' },
+        { name: 'exclude', type: 'string', choices: [...EXCLUDE_CHOICES], help: 'Exclude tweets matching <type>: replies|retweets|media|links. Maps to X\'s `-filter:<x>` operator (retweets → -filter:nativeretweets).' },
         { name: 'limit', type: 'int', default: 15, help: 'Maximum number of tweets to return (default 15). Result count after server-side filtering.' },
         { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the results by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps X\'s native ordering.' },
     ],

package/dist/src/adapter-shadow.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
+import { getUserClisDir } from './config-paths.js';
 import { fileURLToPath } from 'node:url';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 function defaultBuiltinClisDir() {
@@ -31,7 +31,7 @@ function loadBuiltinCommandFiles(builtinClisDir) {
     }
 }
 export function findShadowedUserAdapters(opts = {}) {
-    const userClisDir = opts.userClisDir ?? path.join(os.homedir(), '.bycli', 'clis');
+    const userClisDir = opts.userClisDir ?? getUserClisDir();
     const builtinClisDir = opts.builtinClisDir ?? defaultBuiltinClisDir();
     const builtinCommandFiles = loadBuiltinCommandFiles(builtinClisDir);
     const shadows = [];

package/dist/src/browser/analyze.d.ts

@@ -1,103 +1,14 @@
 /**
- * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ * `browser analyze <url>` — site-recon classification.
  *
- * When an agent starts a new adapter, the first question is "which pattern am
- * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
- * work, or will anti-bot middleware block me?". Today the agent has to open
- * the page, poke `network`, try cURL, fail, guess again. This module condenses
- * that into one call that returns a classification + evidence.
+ * The pure analysis logic moved to the shared package `@sovovs/bycli-recorder-core`
+ * (M5a, same pure-domain split as rank/M4) so dashboard-be can reuse it too. This
+ * module re-exports it so existing main-repo importers (cli.ts, the high-level
+ * analyze module) are unchanged. The CLI wrapper drives a real page, feeds the
+ * resulting PageSignals here, and prints the verdict.
  *
- * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
- * drives a real page, feeds the resulting signals here, and prints the verdict.
+ * Note: the package types the registry as a structural `AdapterRef` ({site,name,
+ * domain?}); the main-repo `CliCommand` is assignable to it, so callers can keep
+ * passing `getRegistry()` (Map<string, CliCommand>) unchanged.
  */
-import type { CliCommand } from '../registry.js';
-export interface PageSignals {
-    /** URL we navigated to (may redirect; both fields help agents notice that). */
-    requestedUrl: string;
-    finalUrl: string;
-    /** document.cookie split into names; value not needed for detection. */
-    cookieNames: string[];
-    /**
-     * Response bodies captured during the navigation + first few seconds.
-     * We only need enough body text to spot WAF markers; the CLI truncates
-     * per-entry before feeding us.
-     */
-    networkEntries: Array<{
-        url: string;
-        status: number;
-        contentType: string;
-        /** First N chars of body; null when not available. */
-        bodyPreview: string | null;
-    }>;
-    /**
-     * Which globals the page exposes on `window`. We don't care about the values,
-     * just presence — distinguishes Pattern B (SSR state) from Pattern A.
-     */
-    initialState: {
-        __INITIAL_STATE__: boolean;
-        __NUXT__: boolean;
-        __NEXT_DATA__: boolean;
-        __APOLLO_STATE__: boolean;
-    };
-    /** Document title — only for the human-debug `summary` field. */
-    title: string;
-}
-export type AntiBotVendor = 'aliyun_waf' | 'cloudflare' | 'akamai' | 'geetest' | 'unknown';
-export interface AntiBotVerdict {
-    detected: boolean;
-    vendor: AntiBotVendor | null;
-    evidence: string[];
-    /** One-line imperative instruction for the agent. */
-    implication: string;
-}
-export declare function detectAntiBot(signals: PageSignals): AntiBotVerdict;
-export type Pattern = 'A' | 'B' | 'C' | 'D' | 'E' | 'unknown';
-export interface PatternVerdict {
-    pattern: Pattern;
-    reason: string;
-    /** How many JSON XHR/fetch responses we saw during navigation. */
-    json_responses: number;
-    /** Count of non-2xx API responses — hint for token-gated (Pattern D). */
-    auth_failures: number;
-}
-/**
- * Apply the decision tree from `site-recon.md` mechanically.
- *
- * B beats A when initial-state globals are present: even if the page fetches
- * more data via XHR afterwards, the SSR payload is the highest-leverage source.
- * D (token-gated) dominates when we see 401/403 on what looks like API
- * endpoints — without that, an authenticated route looks identical to A.
- */
-export declare function classifyPattern(signals: PageSignals): PatternVerdict;
-export interface NearestAdapter {
-    site: string;
-    example_commands: string[];
-    reason: string;
-}
-/**
- * Find existing adapters that target the same site.
- *
- * Keep the hostname match simple — agents extend naming conventions
- * differently per site, so we match on the registered `domain` field and fall
- * back to site-name containment. Returning `null` is fine; agents can always
- * read site-memory docs.
- */
-export declare function findNearestAdapter(finalUrl: string, registry: Map<string, CliCommand>): NearestAdapter | null;
-export interface AnalyzeReport {
-    requested_url: string;
-    final_url: string;
-    title: string;
-    pattern: PatternVerdict;
-    anti_bot: AntiBotVerdict;
-    initial_state: PageSignals['initialState'];
-    nearest_adapter: NearestAdapter | null;
-    recommended_next_step: string;
-}
-/**
- * Synthesize the verdict from collected signals + registry.
- *
- * The `recommended_next_step` is deliberately a single imperative
- * sentence — agents act on it directly instead of re-deriving advice from
- * the structured fields.
- */
-export declare function analyzeSite(signals: PageSignals, registry: Map<string, CliCommand>): AnalyzeReport;
+export { analyzeSite, detectAntiBot, classifyPattern, findNearestAdapter, type AdapterRef, type PageSignals, type AnalyzeReport, type AntiBotVerdict, type AntiBotVendor, type PatternVerdict, type Pattern, type NearestAdapter, } from '@sovovs/bycli-recorder-core';

package/dist/src/browser/analyze.js

@@ -1,230 +1,14 @@
 /**
- * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ * `browser analyze <url>` — site-recon classification.
  *
- * When an agent starts a new adapter, the first question is "which pattern am
- * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
- * work, or will anti-bot middleware block me?". Today the agent has to open
- * the page, poke `network`, try cURL, fail, guess again. This module condenses
- * that into one call that returns a classification + evidence.
+ * The pure analysis logic moved to the shared package `@sovovs/bycli-recorder-core`
+ * (M5a, same pure-domain split as rank/M4) so dashboard-be can reuse it too. This
+ * module re-exports it so existing main-repo importers (cli.ts, the high-level
+ * analyze module) are unchanged. The CLI wrapper drives a real page, feeds the
+ * resulting PageSignals here, and prints the verdict.
  *
- * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
- * drives a real page, feeds the resulting signals here, and prints the verdict.
+ * Note: the package types the registry as a structural `AdapterRef` ({site,name,
+ * domain?}); the main-repo `CliCommand` is assignable to it, so callers can keep
+ * passing `getRegistry()` (Map<string, CliCommand>) unchanged.
  */
-/**
- * WAF vendors we can reliably detect from cookies + response body markers
- * alone. Signals are orthogonal per vendor — so when two vendors match
- * simultaneously (rare), we keep all evidence and report the higher-signal
- * vendor first.
- */
-const WAF_SIGNATURES = [
-    {
-        vendor: 'aliyun_waf',
-        cookiePatterns: [/^acw_sc__v2$/, /^acw_tc$/, /^ssxmod_itna/],
-        bodyPatterns: [/arg1\s*=\s*['"][0-9A-F]{30,}/, /\/ntc_captcha\//i],
-        implication: 'Direct Node-side fetch/curl will return the slider HTML. Validate the endpoint in browser context first; HTML COOKIE adapters still finish with Node-side fetch + page.getCookies.',
-    },
-    {
-        vendor: 'cloudflare',
-        cookiePatterns: [/^__cf_bm$/, /^cf_clearance$/, /^__cfduid$/],
-        bodyPatterns: [/Cloudflare Ray ID/i, /Checking your browser before accessing/i, /cf-chl-/i],
-        implication: 'Cloudflare bot check. Start from a real browser session; probe in browser context first. HTML COOKIE adapters still finish with Node-side fetch + page.getCookies.',
-    },
-    {
-        vendor: 'akamai',
-        cookiePatterns: [/^_abck$/, /^bm_sz$/, /^bm_sv$/],
-        bodyPatterns: [/akamai/i],
-        implication: 'Akamai Bot Manager. Probe in browser context first; keep final HTML COOKIE adapters on Node-side fetch + page.getCookies.',
-    },
-    {
-        vendor: 'geetest',
-        cookiePatterns: [],
-        bodyPatterns: [/geetest/i, /gt_captcha/i],
-        implication: 'Geetest slider/puzzle captcha. Agent cannot bypass programmatically — requires UI strategy or human-in-loop.',
-    },
-];
-export function detectAntiBot(signals) {
-    const evidence = [];
-    let match = null;
-    for (const sig of WAF_SIGNATURES) {
-        const hits = [];
-        for (const pat of sig.cookiePatterns) {
-            const hit = signals.cookieNames.find((c) => pat.test(c));
-            if (hit)
-                hits.push(`cookie:${hit}`);
-        }
-        for (const pat of sig.bodyPatterns) {
-            for (const entry of signals.networkEntries) {
-                if (entry.bodyPreview && pat.test(entry.bodyPreview)) {
-                    hits.push(`body:${entry.url}`);
-                    break;
-                }
-            }
-        }
-        if (hits.length > 0 && !match) {
-            match = sig;
-            evidence.push(...hits);
-        }
-    }
-    if (!match) {
-        return {
-            detected: false,
-            vendor: null,
-            evidence: [],
-            implication: 'No known anti-bot signatures. Try Node-side COOKIE fetch first; if endpoint validation is blocked, retry from browser context.',
-        };
-    }
-    return {
-        detected: true,
-        vendor: match.vendor,
-        evidence,
-        implication: match.implication,
-    };
-}
-/**
- * Apply the decision tree from `site-recon.md` mechanically.
- *
- * B beats A when initial-state globals are present: even if the page fetches
- * more data via XHR afterwards, the SSR payload is the highest-leverage source.
- * D (token-gated) dominates when we see 401/403 on what looks like API
- * endpoints — without that, an authenticated route looks identical to A.
- */
-export function classifyPattern(signals) {
-    const jsonEntries = signals.networkEntries.filter((e) => /json/i.test(e.contentType));
-    const authFailures = signals.networkEntries.filter((e) => e.status === 401 || e.status === 403).length;
-    const hasInitialState = signals.initialState.__INITIAL_STATE__ ||
-        signals.initialState.__NUXT__ ||
-        signals.initialState.__NEXT_DATA__ ||
-        signals.initialState.__APOLLO_STATE__;
-    if (authFailures >= 2 && jsonEntries.length >= 1) {
-        return {
-            pattern: 'D',
-            reason: `${authFailures} auth-failing API responses seen — endpoint is token-gated`,
-            json_responses: jsonEntries.length,
-            auth_failures: authFailures,
-        };
-    }
-    if (hasInitialState) {
-        const which = Object.entries(signals.initialState)
-            .filter(([, v]) => v)
-            .map(([k]) => k);
-        return {
-            pattern: 'B',
-            reason: `SSR state global present: ${which.join(', ')}`,
-            json_responses: jsonEntries.length,
-            auth_failures: authFailures,
-        };
-    }
-    if (jsonEntries.length >= 1) {
-        return {
-            pattern: 'A',
-            reason: `${jsonEntries.length} JSON XHR/fetch responses observed — classic API pattern`,
-            json_responses: jsonEntries.length,
-            auth_failures: authFailures,
-        };
-    }
-    // No API, no SSR state — probably static HTML or a bundled SPA that lazy-loads.
-    // Pattern C (HTML scrape) is the default fallback; E (streaming) we can't
-    // reliably detect without watching WebSocket frames, so we label 'C' and
-    // leave the agent to upgrade to E manually if they see WS traffic.
-    return {
-        pattern: 'C',
-        reason: 'No JSON XHR and no SSR state — HTML scrape (Pattern C); escalate to E manually if WebSocket traffic appears',
-        json_responses: jsonEntries.length,
-        auth_failures: authFailures,
-    };
-}
-/**
- * Find existing adapters that target the same site.
- *
- * Keep the hostname match simple — agents extend naming conventions
- * differently per site, so we match on the registered `domain` field and fall
- * back to site-name containment. Returning `null` is fine; agents can always
- * read site-memory docs.
- */
-export function findNearestAdapter(finalUrl, registry) {
-    let host;
-    try {
-        host = new URL(finalUrl).hostname;
-    }
-    catch {
-        return null;
-    }
-    // Strip leading www.; 'www' as a site identifier is never what an adapter uses.
-    const cleanedHost = host.replace(/^www\./, '');
-    // Extract apex (xx.com) and registrable parts for fuzzy match.
-    const parts = cleanedHost.split('.');
-    const apex = parts.slice(-2).join('.');
-    const siteKey = parts.length > 1 ? parts[parts.length - 2] : cleanedHost;
-    const hits = new Map();
-    for (const cmd of registry.values()) {
-        const domain = cmd.domain?.toLowerCase();
-        const siteMatches = (domain && (cleanedHost.endsWith(domain) || domain.endsWith(apex))) ||
-            cmd.site.toLowerCase() === siteKey?.toLowerCase() ||
-            cleanedHost.includes(cmd.site.toLowerCase());
-        if (siteMatches) {
-            const list = hits.get(cmd.site) ?? [];
-            list.push(cmd);
-            hits.set(cmd.site, list);
-        }
-    }
-    if (hits.size === 0)
-        return null;
-    // Pick the site with the most commands — likely the most-developed adapter,
-    // and the best reference for a new command on the same host.
-    let best = null;
-    for (const entry of hits) {
-        if (!best || entry[1].length > best[1].length)
-            best = entry;
-    }
-    if (!best)
-        return null;
-    return {
-        site: best[0],
-        example_commands: best[1].slice(0, 5).map((c) => `${c.site} ${c.name}`),
-        reason: `${best[1].length} existing adapter${best[1].length === 1 ? '' : 's'} target this site — reuse strategy/cookie config`,
-    };
-}
-/**
- * Synthesize the verdict from collected signals + registry.
- *
- * The `recommended_next_step` is deliberately a single imperative
- * sentence — agents act on it directly instead of re-deriving advice from
- * the structured fields.
- */
-export function analyzeSite(signals, registry) {
-    const pattern = classifyPattern(signals);
-    const antiBot = detectAntiBot(signals);
-    const nearest = findNearestAdapter(signals.finalUrl, registry);
-    let next;
-    if (antiBot.detected) {
-        next = antiBot.implication;
-    }
-    else if (pattern.pattern === 'A') {
-        next = 'Pick the most specific JSON endpoint from `bycli browser network` and try a bare Node fetch with cookies; escalate to browser-context fetch only if blocked.';
-    }
-    else if (pattern.pattern === 'B') {
-        next = 'Read the SSR global via `bycli browser eval "JSON.stringify(window.__INITIAL_STATE__ ?? window.__NUXT__ ?? window.__NEXT_DATA__ ?? window.__APOLLO_STATE__)"` — no API needed.';
-    }
-    else if (pattern.pattern === 'C') {
-        next = 'No API visible — use SSR HTML scrape (e.g. `bycli browser extract`) against the rendered page.';
-    }
-    else if (pattern.pattern === 'D') {
-        next = 'Endpoints need auth. Re-open the page from a signed-in session, then retry analyze; see `field-decode-playbook` §4 for token tracing.';
-    }
-    else if (pattern.pattern === 'E') {
-        next = 'WebSocket stream detected — find the underlying HTTP poll/long-poll endpoint; raw WS is not supported.';
-    }
-    else {
-        next = 'No strong signal. Manually inspect `bycli browser network --all` and pick a pattern.';
-    }
-    return {
-        requested_url: signals.requestedUrl,
-        final_url: signals.finalUrl,
-        title: signals.title,
-        pattern,
-        anti_bot: antiBot,
-        initial_state: signals.initialState,
-        nearest_adapter: nearest,
-        recommended_next_step: next,
-    };
-}
+export { analyzeSite, detectAntiBot, classifyPattern, findNearestAdapter, } from '@sovovs/bycli-recorder-core';

package/dist/src/browser/cdp.js

@@ -13,9 +13,36 @@ import { request as httpsRequest } from 'node:https';
 import { buildEvaluateExpression } from './utils.js';
 import { generateStealthJs } from './stealth.js';
 import { waitForDomStableJs } from './dom-helpers.js';
+import { armNavigationGuard, NavigationBlockedError } from './navigation-guard.js';
+import { checkUrlPolicy } from './url-policy.js';
 import { isRecord, saveBase64ToFile } from '../utils.js';
 import { getAllElectronApps } from '../electron-apps.js';
 import { BasePage } from './base-page.js';
+/** Lazily-built DnsResolver backed by node:dns/promises (for guarded navigation). */
+let _dnsResolver;
+function getDefaultDnsResolver() {
+    if (_dnsResolver)
+        return _dnsResolver;
+    // Imported lazily so the module stays usable in environments without node:dns.
+    const dns = require('node:dns').promises;
+    _dnsResolver = {
+        resolve4: (h) => dns.resolve4(h),
+        resolve6: (h) => dns.resolve6(h),
+    };
+    return _dnsResolver;
+}
+/** Resolve once the guard records a blocked main-frame request (polled). */
+function waitForBlocked(guard, intervalMs = 100, timeoutMs = 30_000) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        const timer = setInterval(() => {
+            if (guard.blocked.length > 0 || Date.now() - start > timeoutMs) {
+                clearInterval(timer);
+                resolve();
+            }
+        }, intervalMs);
+    });
+}
 const CDP_SEND_TIMEOUT = 30_000;
 // Memory guard for in-process capture. The 4k cap we used to apply everywhere
 // silently truncated JSON so `JSON.parse` failed or gave partial objects — the
@@ -172,13 +199,43 @@ class CDPPage extends BasePage {
             await this.bridge.send('Page.enable');
             this._pageEnabled = true;
         }
-        const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
-        await this.bridge.send('Page.navigate', { url });
-        await loadPromise;
-        this._lastUrl = url;
-        if (options?.waitUntil !== 'none') {
-            const maxMs = options?.settleMs ?? 1000;
-            await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+        // Opt-in guarded navigation (M1 P0-1, direct-CDP side). Only the recorder path
+        // sets guardNavigation; general automation (incl. localhost fixtures) is
+        // unchanged. Pre-checks the target (syntax + DNS) and arms Fetch before-send
+        // interception before Page.navigate, so redirects to forbidden targets are
+        // failRequest'd before send. ip-observed-only per ADR-0006.
+        let guard;
+        if (options?.guardNavigation) {
+            const resolver = getDefaultDnsResolver();
+            const pre = await checkUrlPolicy(url, resolver);
+            if (!pre.ok) {
+                throw new NavigationBlockedError(url, pre.reason, pre.detail);
+            }
+            guard = await armNavigationGuard(this.bridge, resolver, { observeIp: true });
+        }
+        try {
+            const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
+            await this.bridge.send('Page.navigate', { url });
+            if (guard) {
+                // A blocked main-frame request never fires loadEventFired — race the load
+                // against a short poll of the guard's blocked list so we don't wait 30s.
+                await Promise.race([loadPromise, waitForBlocked(guard)]);
+                if (guard.blocked.length > 0) {
+                    throw new NavigationBlockedError(url, 'forbidden_ip', `redirect blocked: ${guard.blocked.map((b) => b.url).join(', ')}`);
+                }
+            }
+            else {
+                await loadPromise;
+            }
+            this._lastUrl = url;
+            if (options?.waitUntil !== 'none') {
+                const maxMs = options?.settleMs ?? 1000;
+                await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+            }
+        }
+        finally {
+            if (guard)
+                await guard.dispose();
         }
     }
     async evaluate(input, ...args) {
@@ -201,6 +258,9 @@ class CDPPage extends BasePage {
             ? cookies.filter((cookie) => isCookie(cookie) && matchesCookieDomain(cookie.domain, domain))
             : cookies;
     }
+    async focusWindow() {
+        await this.bridge.send('Page.bringToFront');
+    }
     async screenshot(options = {}) {
         const fullPage = options.fullPage === true;
         const overrideWidth = options.width && options.width > 0 ? Math.ceil(options.width) : undefined;

package/dist/src/browser/daemon-client.d.ts

@@ -68,6 +68,7 @@ export interface DaemonStatus {
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: string;
+    extensionCapabilities?: string[];
     contextId?: string;
     profileRequired?: boolean;
     profileDisconnected?: boolean;
@@ -82,6 +83,7 @@ export interface BrowserProfileStatus {
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: string;
+    extensionCapabilities?: string[];
     pending: number;
     lastSeenAt?: number;
 }

package/dist/src/browser/daemon-client.js

@@ -109,7 +109,7 @@ async function sendCommandRaw(action, params) {
                     throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
                 }
                 const isDuplicateCommandId = res.status === 409
-                    || (result.error ?? '').includes('Duplicate command id');
+                    && (result.error ?? '').includes('Duplicate command id');
                 if (isDuplicateCommandId && attempt < maxRetries) {
                     continue;
                 }

package/dist/src/browser/extension-capabilities.d.ts

@@ -0,0 +1,13 @@
+export declare const FOCUS_WINDOW_CAPABILITY = "focus-window-v1";
+export declare const EXTENSION_CAPABILITY_MISSING_ERROR_CODE = "extension_capability_missing";
+export declare const EXTENSION_CAPABILITY_MISSING_HTTP_STATUS = 412;
+export declare function normalizeExtensionCapabilities(value: unknown): string[];
+export declare function requiredExtensionCapability(command: {
+    action?: unknown;
+    op?: unknown;
+}): string | undefined;
+export declare function missingRequiredExtensionCapability(command: {
+    action?: unknown;
+    op?: unknown;
+}, capabilities: readonly string[]): string | undefined;
+export declare function extensionCapabilityHint(capability: string): string;

package/dist/src/browser/extension-capabilities.js

@@ -0,0 +1,22 @@
+export const FOCUS_WINDOW_CAPABILITY = 'focus-window-v1';
+export const EXTENSION_CAPABILITY_MISSING_ERROR_CODE = 'extension_capability_missing';
+export const EXTENSION_CAPABILITY_MISSING_HTTP_STATUS = 412;
+export function normalizeExtensionCapabilities(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.filter((entry) => typeof entry === 'string' && entry.length > 0))];
+}
+export function requiredExtensionCapability(command) {
+    return command.action === 'tabs' && command.op === 'focus'
+        ? FOCUS_WINDOW_CAPABILITY
+        : undefined;
+}
+export function missingRequiredExtensionCapability(command, capabilities) {
+    const required = requiredExtensionCapability(command);
+    return required && !capabilities.includes(required) ? required : undefined;
+}
+export function extensionCapabilityHint(capability) {
+    return capability === FOCUS_WINDOW_CAPABILITY
+        ? 'Update and reload the byCLI Browser Bridge extension, then retry the login flow.'
+        : 'Update and reload the byCLI Browser Bridge extension, then retry.';
+}

package/dist/src/browser/extension-capabilities.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/extension-version-metadata.test.d.ts

@@ -0,0 +1 @@
+export {};