@staswhitemustache/ai-search-agent 1.0.0

package/README.md

@@ -0,0 +1,10 @@
+# runner_crawlee (docs moved)
+
+Документация по раннерам лежит в `docs/`:
+- `docs/INDEX.md`
+- `docs/runners/CRAWLEE.md`
+- `docs/runners/GOOGLE.md`
+- `docs/runners/YANDEX_UNIFIED_SPEC.md`
+
+Этот файл оставлен только как краткий указатель.
+

package/README_AGENT.md

@@ -0,0 +1,26 @@
+# AI Search Agent (npm)
+
+Local operator agent for profile creation flow:
+
+- polls backend control state;
+- starts/stops `profile_worker`;
+- opens headful browser on operator machine for manual login.
+
+## Run (after install)
+
+```bash
+ai-search-agent --server https://parser.iseopro.ru --token <LOCAL_AGENT_TOKEN> --agent-id operator-pc-1 --install
+```
+
+## Environment alternatives
+
+- `PROFILE_AGENT_SERVER`
+- `PROFILE_AGENT_TOKEN`
+- `PROFILE_WORKER_ID`
+- `PROFILE_AGENT_POLL_MS`
+- `PROFILE_AGENT_INSTALL=1`
+
+## Notes
+
+- `--install` installs package dependencies if missing and always runs `playwright install chromium`.
+- Agent token is generated by backend UI and can be revoked/rotated there.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@staswhitemustache/ai-search-agent",
+  "version": "1.0.0",
+  "description": "Crawlee+Playwright runner для MVP сравнения стеков",
+  "main": "runner.js",
+  "type": "module",
+  "files": [
+    "tools/profile_local_agent.js",
+    "tools/profile_worker.js",
+    "tools/yandex_profile_save.js",
+    "shared/account_utils.js",
+    "shared/profile_manager.js",
+    "shared/proxy_pool.js",
+    "shared/yandex_auth.js",
+    "shared/runner_common.js",
+    "shared/crawlee_storage.js",
+    "README_AGENT.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "bin": {
+    "ai-search-agent": "tools/profile_local_agent.js"
+  },
+  "scripts": {
+    "start": "node runner.js",
+    "google": "node runner_google.js",
+    "yandex": "node runner_yandex_profiles.js",
+    "profile-worker": "node tools/profile_worker.js",
+    "profile-worker-controller": "node tools/profile_worker_controller.js",
+    "profile-local-agent": "node tools/profile_local_agent.js",
+    "agent:pack-dry-run": "npm pack --dry-run",
+    "agent:publish-public": "npm publish --access public"
+  },
+  "dependencies": {
+    "@crawlee/browser-pool": "^3.15.3",
+    "crawlee": "^3.7.0",
+    "fingerprint-generator": "^2.1.80",
+    "fingerprint-injector": "^2.1.80",
+    "header-generator": "^2.1.80",
+    "ioredis": "^5.4.2",
+    "playwright": "^1.40.0"
+  }
+}

package/runner.js

@@ -0,0 +1,2 @@
+// Backward-compatible entrypoint (старое имя файла).
+import './runner_google.js';

package/shared/account_utils.js

@@ -0,0 +1,149 @@
+/**
+ * Утилиты для работы с аккаунтами Yandex и прокси.
+ * Централизованный модуль для избежания дублирования кода.
+ */
+import { existsSync, readFileSync } from 'fs';
+
+/**
+ * Маскирование логина для безопасного логирования.
+ * @param {string} login - Полный логин
+ * @returns {string|null} - Маскированный логин (первые 3 символа + ***)
+ */
+export function maskLogin(login) {
+    const s = String(login || '');
+    if (!s) return null;
+    if (s.length <= 3) return `${s[0] || ''}***`;
+    return `${s.slice(0, 3)}***`;
+}
+
+/**
+ * Маскирование proxy URL для безопасного логирования.
+ * @param {string} proxyUrl - Полный proxy URL с креденшалами
+ * @returns {string} - Маскированный proxy (host:port)
+ */
+export function maskProxy(proxyUrl) {
+    try {
+        const u = new URL(proxyUrl);
+        return `${u.hostname}:${u.port}`;
+    } catch {
+        return 'unknown';
+    }
+}
+
+/**
+ * Загрузка аккаунтов Yandex из файла.
+ * Формат: login:password:answer (одна строка = один аккаунт)
+ *
+ * @param {string} filePath - Путь к файлу с аккаунтами
+ * @returns {Array<{login: string, password: string, answer: string|null}>}
+ */
+export function loadAccounts(filePath) {
+    const out = [];
+    if (!filePath || !existsSync(filePath)) return out;
+
+    const lines = readFileSync(filePath, 'utf-8')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('#'));
+
+    for (const line of lines) {
+        const parts = line.split(':');
+        if (parts.length < 2) continue;
+        const login = (parts[0] || '').trim();
+        const password = (parts[1] || '').trim();
+        const answer = (parts[2] || '').trim();
+        if (!login || !password) continue;
+        out.push({ login, password, answer: answer || null });
+    }
+
+    return out;
+}
+
+/**
+ * Загрузка прокси из файла.
+ * Формат: username:password@host:port (одна строка = один прокси)
+ *
+ * @param {string} filePath - Путь к файлу с прокси
+ * @returns {Array<string>} - Массив proxy URLs (http://user:pass@host:port)
+ */
+/**
+ * Выбор User-Agent для десктопа (Windows/Chrome) на основе seed.
+ * Использует детерминированный хеш для стабильного выбора UA для каждого seed.
+ *
+ * @param {string} seed - Seed для выбора UA (например, login аккаунта)
+ * @returns {string} - User-Agent строка
+ */
+export function pickDesktopUserAgent(seed) {
+    // Современные UA для Chrome 130-135 (конец 2025 - начало 2026)
+    const pool = [
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36',
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36',
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
+    ];
+
+    const str = String(seed || '');
+    let h = 0;
+    for (let i = 0; i < str.length; i++) h = (h * 31 + str.charCodeAt(i)) >>> 0;
+    return pool[h % pool.length];
+}
+
+/**
+ * Логика "прогрева" Yandex сессии — имитация естественного поведения пользователя.
+ *
+ * Важно: не используем прямой поиск в warmup, чтобы не триггерить антифрод.
+ * Поведение: перейти на пару сайтов → вернуться на главную Яндекса.
+ *
+ * @param {import('playwright').Page} page - Playwright page
+ * @param {boolean} verbose - Детальное логирование
+ */
+export async function warmupYandexSession(page, verbose = false) {
+    const sites = ['https://vc.ru', 'https://habr.com'];
+
+    for (const url of sites) {
+        if (verbose) console.log(`[warmup] Переход на ${url}...`);
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        await page.waitForTimeout(600).catch(() => null);
+        try {
+            await page.evaluate(() => window.scrollTo(0, 200));
+            await page.waitForTimeout(250);
+            await page.evaluate(() => window.scrollTo(0, 0));
+        } catch {
+            // ignore
+        }
+    }
+
+    if (verbose) console.log('[warmup] Возврат на главную ya.ru...');
+    await page.goto('https://ya.ru/', { waitUntil: 'domcontentloaded', timeout: 30000 });
+    await page.waitForTimeout(800).catch(() => null);
+
+    const searchInput = await page.waitForSelector('input[name="text"], input#text', { timeout: 15000 }).catch(() => null);
+    if (!searchInput) {
+        if (verbose) console.log('[warmup] Поисковая строка не найдена, завершаем warmup');
+        return;
+    }
+
+    await searchInput.click().catch(() => null);
+    await page.waitForTimeout(200).catch(() => null);
+
+    if (verbose) console.log('[warmup] Прогрев завершён');
+}
+
+/**
+ * Универсальная функция для клика по элементу, если он видим.
+ *
+ * @param {import('playwright').Page} page - Playwright page
+ * @param {import('playwright').Locator} locator - Locator элемента
+ * @param {number} timeoutMs - Таймаут ожидания
+ * @returns {Promise<boolean>} - true если клик успешен, false если элемент не найден
+ */
+export async function clickIfVisible(page, locator, timeoutMs = 1500) {
+    try {
+        await locator.first().waitFor({ state: 'visible', timeout: timeoutMs });
+        await locator.first().click({ timeout: timeoutMs });
+        return true;
+    } catch {
+        return false;
+    }
+}

package/shared/crawlee_storage.js

@@ -0,0 +1,17 @@
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { Configuration } from 'crawlee';
+
+/**
+ * Делает уникальную директорию хранилища Crawlee для каждого run/engine.
+ * Это устраняет EBUSY/lock конфликты на Windows/OneDrive при параллельных запусках.
+ */
+export function setupCrawleeStorage({ runDir, engine }) {
+    const storageDir = join(runDir, 'crawlee_storage', engine);
+    mkdirSync(storageDir, { recursive: true });
+
+    // Надёжнее, чем env: устанавливаем через Configuration.
+    Configuration.getGlobalConfig().set('storageDir', storageDir);
+    return storageDir;
+}
+

package/shared/profile_manager.js

@@ -0,0 +1,223 @@
+/**
+ * Profile Manager для Yandex аккаунтов.
+ *
+ * Управляет профилями (account + proxy + UA + storageState) для стабильного reuse сессий.
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+function hasStorageState(profile) {
+    if (!profile || typeof profile !== 'object') return false;
+    if (profile.storageState && typeof profile.storageState === 'object') return true;
+    return !!(profile.storageStatePath && existsSync(profile.storageStatePath));
+}
+
+/**
+ * Парсинг proxy URL в объект параметров для Playwright.
+ */
+export function parseProxyUrl(proxyUrl) {
+    const u = new URL(proxyUrl);
+    return {
+        server: `${u.protocol}//${u.hostname}:${u.port}`,
+        username: decodeURIComponent(u.username || ''),
+        password: decodeURIComponent(u.password || ''),
+        host: u.hostname,
+        port: Number(u.port),
+    };
+}
+
+/**
+ * Загрузка профиля из файла.
+ */
+export function loadProfile(profilePath) {
+    if (!existsSync(profilePath)) {
+        throw new Error(`profile_not_found: ${profilePath}`);
+    }
+
+    const profile = JSON.parse(readFileSync(profilePath, 'utf-8'));
+
+    if (!hasStorageState(profile)) {
+        throw new Error(`storage_state_not_found for profile: ${profilePath}`);
+    }
+
+    return profile;
+}
+
+/**
+ * Load profiles from base64-encoded JSON payload.
+ */
+export function loadProfilesFromPayload(payloadB64) {
+    if (!payloadB64 || typeof payloadB64 !== 'string') return [];
+    let parsed;
+    try {
+        const raw = Buffer.from(payloadB64, 'base64').toString('utf-8');
+        parsed = JSON.parse(raw);
+    } catch (e) {
+        throw new Error(`invalid_profiles_payload: ${e?.message || e}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('invalid_profiles_payload: expected array');
+    }
+
+    const profiles = [];
+    const usedAccountIds = new Set();
+
+    for (const p of parsed) {
+        try {
+            if (!p || typeof p !== 'object') continue;
+            if (p.valid === false || p.isValid === false || p.disabled === true) continue;
+            if (p.status && p.status !== 'ok') continue;
+            if (!hasStorageState(p)) continue;
+            if (p.accountId && usedAccountIds.has(p.accountId)) continue;
+            if (p.accountId) usedAccountIds.add(p.accountId);
+            profiles.push(p);
+        } catch {
+            // skip bad rows
+        }
+    }
+
+    return profiles;
+}
+
+/**
+ * Загрузка всех профилей из директории.
+ */
+export function loadAllProfiles(profileDir) {
+    if (!existsSync(profileDir)) {
+        return [];
+    }
+
+    const entries = readdirSync(profileDir, { withFileTypes: true });
+    const profiles = [];
+    const usedAccountIds = new Set();
+
+    function isValidProfileMeta(profile) {
+        if (!profile) return false;
+        if (profile.valid === false) return false;
+        if (profile.isValid === false) return false;
+        if (profile.disabled === true) return false;
+        if (profile.status && profile.status !== 'ok') return false;
+        return true;
+    }
+
+    function shouldSkipByResult(resultPath) {
+        if (!existsSync(resultPath)) return false;
+        try {
+            const result = JSON.parse(readFileSync(resultPath, 'utf-8'));
+            if (result?.ok === false) return true;
+            if (result?.status && !['ok', 'valid'].includes(result.status)) return true;
+        } catch {
+            return true;
+        }
+        return false;
+    }
+
+    function tryAddProfile(profilePath, logLabel, resultPath = null) {
+        try {
+            if (resultPath && shouldSkipByResult(resultPath)) {
+                console.warn(`[profile_manager] Skipped invalid profile: ${logLabel}`);
+                return;
+            }
+            const profile = loadProfile(profilePath);
+            if (!isValidProfileMeta(profile)) {
+                console.warn(`[profile_manager] Skipped invalid profile meta: ${logLabel}`);
+                return;
+            }
+            if (profile.accountId && usedAccountIds.has(profile.accountId)) {
+                console.warn(`[profile_manager] Skipped duplicate accountId: ${profile.accountId}`);
+                return;
+            }
+            if (profile.accountId) usedAccountIds.add(profile.accountId);
+            profiles.push(profile);
+        } catch (e) {
+            console.warn(`[profile_manager] Failed to load ${logLabel}: ${e?.message}`);
+        }
+    }
+
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('_profile.json')) {
+            const profilePath = join(profileDir, entry.name);
+            tryAddProfile(profilePath, entry.name);
+        }
+    }
+
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const profilePath = join(profileDir, entry.name, 'profile.json');
+        if (!existsSync(profilePath)) continue;
+        const resultPath = join(profileDir, entry.name, 'result.json');
+        tryAddProfile(profilePath, `${entry.name}/profile.json`, resultPath);
+    }
+
+    return profiles;
+}
+
+/**
+ * Создание Playwright браузера и контекста из профиля.
+ *
+ * КРИТИЧНО: все параметры должны совпадать с теми, что были при сохранении!
+ *
+ * NOTE: Proxy ДОЛЖЕН быть на уровне browser.launch(), а не context.newContext()!
+ */
+export async function createBrowserAndContextFromProfile(
+    chromium,
+    profile,
+    headless = true,
+    proxyUrlOverride = null,
+    allowNoProxy = false
+) {
+    const proxyUrl = proxyUrlOverride || profile.proxyUrl;
+    if (!proxyUrl && !allowNoProxy) {
+        throw new Error('proxy_url_missing');
+    }
+
+    const launchOptions = { headless };
+    if (proxyUrl) {
+        const proxy = parseProxyUrl(proxyUrl);
+        launchOptions.proxy = {
+            server: proxy.server,
+            username: proxy.username,
+            password: proxy.password,
+        };
+    }
+
+    const browser = await chromium.launch(launchOptions);
+
+    const contextOptions = {
+        userAgent: profile.userAgent || 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+        viewport: profile.viewport || { width: 1280, height: 900 },
+        locale: profile.locale || 'ru-RU',
+        timezoneId: profile.timezoneId || 'Europe/Moscow',
+    };
+    if (profile.storageState && typeof profile.storageState === 'object') {
+        contextOptions.storageState = profile.storageState;
+    } else if (profile.storageStatePath && existsSync(profile.storageStatePath)) {
+        contextOptions.storageState = profile.storageStatePath;
+    }
+    const context = await browser.newContext(contextOptions);
+
+    return { browser, context };
+}
+
+/**
+ * Round-robin выбор профиля из пула.
+ */
+export class ProfilePool {
+    constructor(profiles) {
+        this.profiles = profiles;
+        this.index = 0;
+    }
+
+    next() {
+        if (!this.profiles.length) {
+            throw new Error('ProfilePool is empty');
+        }
+        const profile = this.profiles[this.index % this.profiles.length];
+        this.index++;
+        return profile;
+    }
+
+    size() {
+        return this.profiles.length;
+    }
+}

package/shared/proxy_pool.js

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync } from 'fs';
+
+function normalizeProvider(raw) {
+    if (!raw) return null;
+    const host = String(raw.host || '').trim();
+    const protocol = String(raw.protocol || 'http').trim() || 'http';
+    const portFrom = Number(raw.port_from ?? raw.portFrom);
+    const portTo = Number(raw.port_to ?? raw.portTo ?? raw.port_from ?? raw.portFrom);
+    if (!host || !Number.isFinite(portFrom) || !Number.isFinite(portTo)) return null;
+    const pf = Math.max(1, Math.min(65535, Math.floor(portFrom)));
+    const pt = Math.max(1, Math.min(65535, Math.floor(portTo)));
+    const port_from = Math.min(pf, pt);
+    const port_to = Math.max(pf, pt);
+    return {
+        id: raw.id != null ? Number(raw.id) : null,
+        host,
+        protocol,
+        port_from,
+        port_to,
+        username: raw.username ? String(raw.username) : null,
+        password: raw.password ? String(raw.password) : null,
+        status: raw.status ? String(raw.status) : 'active',
+        _cursor: port_from,
+    };
+}
+
+function parseProviderLine(line) {
+    const raw = String(line || '').trim();
+    if (!raw || raw.startsWith('#')) return null;
+    const re = /^(?:(?<user>[^:@\s]+):(?<pass>[^@\s]+)@)?(?<host>[^:\s]+):(?<port_from>\d{2,5})(?:-(?<port_to>\d{2,5}))?$/;
+    const m = raw.match(re);
+    if (!m?.groups) return null;
+    const host = m.groups.host;
+    const port_from = Number(m.groups.port_from);
+    const port_to = Number(m.groups.port_to ?? m.groups.port_from);
+    if (!host || !Number.isFinite(port_from) || !Number.isFinite(port_to)) return null;
+    return {
+        host,
+        port_from,
+        port_to,
+        username: m.groups.user || null,
+        password: m.groups.pass || null,
+        protocol: 'http',
+        status: 'active',
+    };
+}
+
+export function loadProxyProvidersFromFile(filePath) {
+    if (!filePath || !existsSync(filePath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(filePath, 'utf-8').trim();
+        if (!content) return [];
+        if (content.startsWith('[')) {
+            const arr = JSON.parse(content);
+            return (Array.isArray(arr) ? arr : [])
+                .map(normalizeProvider)
+                .filter(Boolean);
+        }
+        const lines = content.split('\n');
+        return lines.map(parseProviderLine).map(normalizeProvider).filter(Boolean);
+    } catch (e) {
+        return [];
+    }
+}
+
+export function loadProxyProvidersFromPayload(payloadB64) {
+    const rawPayload = String(payloadB64 || '').trim();
+    if (!rawPayload) return [];
+    let decoded = '';
+    try {
+        decoded = Buffer.from(rawPayload, 'base64').toString('utf-8');
+    } catch (e) {
+        throw new Error(`invalid base64 payload: ${e?.message || e}`);
+    }
+    let arr = null;
+    try {
+        arr = JSON.parse(decoded);
+    } catch (e) {
+        throw new Error(`invalid payload json: ${e?.message || e}`);
+    }
+    if (!Array.isArray(arr)) {
+        throw new Error('proxy payload must be a JSON array');
+    }
+    return arr.map(normalizeProvider).filter(Boolean);
+}
+
+export function buildProxyUrl(provider, port) {
+    const protocol = (provider.protocol || 'http').trim() || 'http';
+    const host = provider.host;
+    const username = provider.username ? encodeURIComponent(provider.username) : '';
+    const password = provider.password ? encodeURIComponent(provider.password) : '';
+    const auth = username || password ? `${username}:${password}@` : '';
+    return `${protocol}://${auth}${host}:${intPort(port)}`;
+}
+
+function intPort(port) {
+    const v = Number(port);
+    if (!Number.isFinite(v)) return 0;
+    return Math.max(1, Math.min(65535, Math.floor(v)));
+}
+
+export class ProxyAllocator {
+    constructor(providers, { leaseMs = 90000, randomize = false } = {}) {
+        this.providers = (providers || []).map(normalizeProvider).filter(Boolean);
+        this.leaseMs = Number(leaseMs) > 0 ? Number(leaseMs) : 90000;
+        this.busy = new Map();
+        this.index = 0;
+        this.randomize = Boolean(randomize);
+    }
+
+    size() {
+        return this.providers.length;
+    }
+
+    _cleanup() {
+        const now = Date.now();
+        for (const [key, exp] of this.busy.entries()) {
+            if (exp <= now) this.busy.delete(key);
+        }
+    }
+
+    _nextPort(provider) {
+        const from = provider.port_from;
+        const to = provider.port_to;
+        if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
+        if (provider._cursor == null || provider._cursor < from || provider._cursor > to) {
+            provider._cursor = from;
+        } else {
+            provider._cursor += 1;
+            if (provider._cursor > to) provider._cursor = from;
+        }
+        return provider._cursor;
+    }
+
+    _randomPort(provider) {
+        const from = provider.port_from;
+        const to = provider.port_to;
+        if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
+        const min = Math.min(from, to);
+        const max = Math.max(from, to);
+        const span = max - min + 1;
+        if (span <= 0) return null;
+        return min + Math.floor(Math.random() * span);
+    }
+
+    acquire() {
+        this._cleanup();
+        if (!this.providers.length) return null;
+        const total = this.providers.length;
+        if (this.randomize) {
+            const attempts = Math.max(20, total * 3);
+            for (let i = 0; i < attempts; i += 1) {
+                const provider = this.providers[Math.floor(Math.random() * total)];
+                const port = this._randomPort(provider);
+                if (!port) continue;
+                const key = `${provider.host}:${port}`;
+                if (!this.busy.has(key)) {
+                    this.busy.set(key, Date.now() + this.leaseMs);
+                    return { provider, port, proxyUrl: buildProxyUrl(provider, port) };
+                }
+            }
+            // Fallback to sequential if random selection couldn't find a free port
+        }
+        for (let i = 0; i < total; i += 1) {
+            const idx = (this.index + i) % total;
+            const provider = this.providers[idx];
+            const port = this._nextPort(provider);
+            if (!port) continue;
+            const key = `${provider.host}:${port}`;
+            if (!this.busy.has(key)) {
+                this.busy.set(key, Date.now() + this.leaseMs);
+                this.index = (idx + 1) % total;
+                return { provider, port, proxyUrl: buildProxyUrl(provider, port) };
+            }
+        }
+        // Fallback: all busy, return next port from current provider
+        const provider = this.providers[this.index % total];
+        const port = this._nextPort(provider);
+        if (!port) return null;
+        const key = `${provider.host}:${port}`;
+        this.busy.set(key, Date.now() + this.leaseMs);
+        this.index = (this.index + 1) % total;
+        return { provider, port, proxyUrl: buildProxyUrl(provider, port) };
+    }
+
+    release(provider, port) {
+        if (!provider || !port) return;
+        const key = `${provider.host}:${intPort(port)}`;
+        this.busy.delete(key);
+    }
+
+    releaseByUrl(url) {
+        try {
+            const u = new URL(url);
+            const host = u.hostname;
+            const port = intPort(u.port);
+            if (!host || !port) return;
+            const key = `${host}:${port}`;
+            this.busy.delete(key);
+        } catch {
+            // ignore
+        }
+    }
+}