Files
edge-kit/index.js
T

1552 lines
80 KiB
JavaScript

/**
* Edge Kit Browser v3 — browsing the way a human does it.
*
* Local branch overlay: EDGE_KIT_NATIVE_FIXES (pending review in 'native-fixes').
*
* Design: agents perceive with `see` (visible text + numbered actionable
* elements, across shadow DOM and dialogs), act like a person (`click` a
* numbered element or the text they can read, `type` into a field by its
* human label, `press` keys, `scroll`, wait for content to appear), verify
* with `screenshot`, and organize work in tabs.
*
* Live-attach-first: if a DevTools-enabled Edge is already listening we
* attach to it (and "close" only detaches — we never close a borrowed
* browser). Otherwise we launch: the user's real Edge profile with
* realProfile:true, or the persistent kit profile. Raw CDP, zero deps.
*/
import os from 'node:os';
import path from 'node:path';
import net from 'node:net';
import { spawn, exec } from 'node:child_process';
import { promises as fs } from 'node:fs';
// schemastery ships inside the app bundle; a profile-linked package cannot
// resolve it by bare name, so import it from the running installation (the
// very file the Web search plugin loads). If that ever fails to resolve, the
// kit still works — only the settings page stays hidden.
/* EDGE_KIT_NATIVE_PORTABILITY: resolve schemastery from the running DeepSeek Harness
* installation instead of a hardcoded per-user path. Candidate roots cover Electron's
* resources directory (with app.asar), a resources folder beside the executable, and the
* per-user install location; the CommonJS build is tried before the ES module build. If
* none resolves the kit still runs and only the settings page stays hidden. */
let z = null;
try {
await (async () => {
const [{ createRequire }, { pathToFileURL }, pathMod] = await Promise.all([
import('node:module'),
import('node:url'),
import('node:path'),
]);
const requireFromHere = createRequire(import.meta.url);
const roots = [];
try { if (process.resourcesPath) roots.push(process.resourcesPath); } catch { /* not Electron */ }
try { roots.push(pathMod.join(pathMod.dirname(process.execPath), 'resources')); } catch { /* no execPath */ }
if (process.env.LOCALAPPDATA) roots.push(pathMod.join(process.env.LOCALAPPDATA, 'Programs', 'DeepSeek Harness', 'resources'));
for (const root of roots) {
const base = pathMod.join(root, 'app.asar', 'dsh', 'node_modules', '@deepseek-ai', 'schemastery');
try {
const cjs = requireFromHere(pathMod.join(base, 'lib', 'index.cjs'));
z = (cjs && (cjs.default || cjs)) || null;
} catch { /* try the ES module build next */ }
if (z) break;
try {
const esm = await import(pathToFileURL(pathMod.join(base, 'lib', 'index.mjs')).href);
z = (esm && (esm.default || esm)) || null;
} catch { /* try the next candidate root */ }
if (z) break;
}
})();
} catch { z = null; }
export const inject = ['tools', 'web'];
/**
* Persistent defaults, editable on this plugin's native settings page in
* DeepSeek (Plugins > Edge Kit Browser) — the same surface the Web search
* plugin uses. Every field is volatile, so saving on the page updates the kit
* live without a restart and the running browser session survives. Per-call
* tool arguments still override these values.
*/
export const Config = z && z.object({
realProfile: z.boolean()
.description('Use your everyday signed-in Edge profile when launching, so saved logins and cookies are available. Turn off to browse in a fresh, isolated Edge Kit profile.')
.default(true).volatile(),
port: z.number()
.description('DevTools port Edge Kit launches Edge with, and attaches to when a debuggable Edge is already listening.')
.step(1).min(1).max(65535).default(9444).volatile(),
headless: z.boolean()
.description('Start Edge without a visible window. Leave off so browsing behaves like a person looking at a screen.')
.default(false).volatile(),
profileDir: z.string()
.description('Where an isolated Edge Kit profile lives when using your signed-in profile is off. Leave blank for the default location.')
.volatile(),
executablePath: z.string()
.description('Full path to msedge.exe. Leave blank to use Edge in its default install locations.')
.volatile(),
seeTextCap: z.number()
.description('How much visible page text the see action returns before truncating (200-6000 characters).')
.step(1).min(200).max(6000).default(2200).volatile(),
searchEngine: z.string()
.description('Which search engine the kit drives for native web_search: "google" or "bing".')
.default('google').volatile(),
browser: z.string()
.description('Which browser the kit launches by default: "edge", "chrome", or "firefox". The launch action can still pick another per call.')
.default('edge').volatile(),
proxyChain: z.string()
.description('Proxy applied to every launch: "ip:port", or comma-separated hops "ip:port,ip:port" — two or more chain through an in-kit local forwarder. The proxy action can test candidates and swap this live.')
.volatile(),
fetchTextCap: z.number()
.description('Maximum characters of rendered page text returned by native web_fetch (it reads pages through your browser, so JavaScript sites work and bot walls pass).')
.step(1).min(1000).max(60000).default(20000).volatile(),
});
let cfg = null; // bound by apply(); volatile fields are read through .get()
const cfgVal = (field, fallback) => {
const f = cfg?.[field];
if (f === undefined || f === null) return fallback;
const v = typeof f.get === 'function' ? f.get() : f;
return v === undefined || v === '' ? fallback : v;
};
const effectivePort = (args) => (Number.isInteger(args?.port) ? args.port : cfgVal('port', 9444));
const settingsSnapshot = () => ({
realProfile: cfgVal('realProfile', true),
port: cfgVal('port', 9444),
headless: cfgVal('headless', false),
profileDir: cfgVal('profileDir', ''),
executablePath: cfgVal('executablePath', ''),
seeTextCap: cfgVal('seeTextCap', 2200),
browser: cfgVal('browser', 'edge'),
proxyChain: cfgVal('proxyChain', ''),
});
const DEFAULT_PORT = 9444;
const KIT_PROFILE = path.join(os.homedir(), '.dsh', 'browser-profiles', 'edge-kit');
// Real signed-in profiles per platform (Windows / Linux / macOS layouts).
const REAL_PROFILE = process.env.LOCALAPPDATA
? path.join(process.env.LOCALAPPDATA, 'Microsoft', 'Edge', 'User Data')
: process.platform === 'linux' ? path.join(os.homedir(), '.config', 'microsoft-edge')
: process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support', 'Microsoft Edge')
: null;
const CHROME_REAL_PROFILE = process.env.LOCALAPPDATA
? path.join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'User Data')
: process.platform === 'linux' ? path.join(os.homedir(), '.config', 'google-chrome')
: process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support', 'Google', 'Chrome')
: null;
const FF_PROFILES_ROOT = process.env.APPDATA
? path.join(process.env.APPDATA, 'Mozilla', 'Firefox')
: process.platform === 'linux' || process.platform === 'darwin' ? path.join(os.homedir(), '.mozilla', 'firefox')
: null;
const IS_WIN = process.platform === 'win32';
const BROWSER_CANDIDATES = {
edge: IS_WIN ? [
'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
] : process.platform === 'darwin' ? [
'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
] : [
'/opt/microsoft/msedge/msedge', '/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable', '/opt/edge/msedge',
],
chrome: IS_WIN ? [
'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
process.env.LOCALAPPDATA + '\\Google\\Chrome\\Application\\chrome.exe',
] : process.platform === 'darwin' ? [
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
] : [
'/opt/google/chrome/chrome', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable',
'/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium',
],
firefox: IS_WIN ? [
'C:\\Program Files\\Mozilla Firefox\\firefox.exe',
'C:\\Program Files (x86)\\Mozilla Firefox\\firefox.exe',
process.env.LOCALAPPDATA + '\\Mozilla Firefox\\firefox.exe',
] : process.platform === 'darwin' ? [
'/Applications/Firefox.app/Contents/MacOS/firefox',
] : [
'/usr/lib/firefox/firefox', '/usr/bin/firefox', '/snap/bin/firefox',
],
};
const kindOf = (exe) => /firefox/i.test(exe) ? 'firefox' : /edge/i.test(exe) ? 'edge' : /chrom/i.test(exe) ? 'chrome' : 'edge';
// Firefox's real profile is whichever profiles.ini marks Default=1.
async function ffDefaultProfile() {
if (!FF_PROFILES_ROOT) return null;
try {
const ini = await fs.readFile(path.join(FF_PROFILES_ROOT, 'profiles.ini'), 'utf8');
let cur = null, pick = null, pickPath = null, pickRel = 1;
for (const line of ini.split(/\r?\n/)) {
const s = line.trim();
if (s.startsWith('[')) { cur = s.slice(1, -1); continue; }
const m = /^(Path|Default|IsRelative)=(.*)$/i.exec(s);
if (!m || !cur?.startsWith('Profile')) continue;
const key = m[1].toLowerCase(), val = m[2].trim();
if (key === 'default' && val === '1') pick = cur;
if (key === 'path' && pick === cur) pickPath = val;
if (key === 'path' && pick === cur && pickPath) pickRel = pickRel; // keep default relative=1
if (key === 'isrelative' && pick === cur) pickRel = Number(val) || 0;
}
if (!pickPath) return null;
return pickRel ? path.join(FF_PROFILES_ROOT, pickPath) : pickPath;
} catch { return null; }
}
let session = null; // { ws, port, child, headless, profileDir, attached, sessionId, targetId }
let lastElements = []; // numbered elements from the most recent see, with rects
let nextId = 1;
const pending = new Map();
const eventHooks = new Set();
function requireSession() {
if (!session || session.ws.readyState !== 1) {
throw new Error('no active Edge session; call "launch" or "attach" first');
}
return session;
}
function send(method, params = {}, sessionId) {
const s = requireSession();
if (s.engine === 'bidi') return (async () => { if (!s.bidiReady) await bidiHandshake(); return bidiSend(method, params, sessionId === null ? undefined : (sessionId ?? s.sessionId)); })();
const { ws } = s;
const id = nextId++;
const sid = sessionId === null ? undefined : (sessionId ?? session.sessionId);
return new Promise((resolve, reject) => {
const timer = setTimeout(() => {
pending.delete(id);
reject(new Error(`CDP timeout: ${method}`));
}, 30000);
pending.set(id, { resolve, reject, timer });
const frame = { id, method, params };
if (sid !== undefined) frame.sessionId = sid;
ws.send(JSON.stringify(frame));
});
}
function onMessage(raw) {
let msg;
try { msg = JSON.parse(raw); } catch { return; }
if (msg.id && pending.has(msg.id)) {
const { resolve, reject, timer } = pending.get(msg.id);
pending.delete(msg.id);
clearTimeout(timer);
if (msg.error) reject(new Error(typeof msg.error === 'string' ? `BiDi ${msg.error}: ${msg.message || ''}` : `CDP ${msg.error.code}: ${msg.error.message}`));
else resolve(msg.result);
return;
}
if (msg.method) {
if (session && session.engine === 'bidi') {
if (msg.method === 'browsingContext.load' || msg.method === 'browsingContext.domContentLoaded' || msg.method === 'browsingContext.navigationComplete') {
for (const hook of [...eventHooks]) hook({ method: 'Page.loadEventFired', sessionId: msg.params && msg.params.context });
}
return;
}
for (const hook of [...eventHooks]) hook(msg);
}
}
async function probePort(port) {
try {
const res = await fetch(`http://127.0.0.1:${port}/json/version`);
if (res.ok) return await res.json();
// Firefox answers here with its httpd.js server and 404s the CDP HTTP
// endpoints — its debug dialect is WebDriver BiDi over ws://…/session.
if (res.status === 404) {
const root = await fetch(`http://127.0.0.1:${port}/`).catch(() => null);
if (root && (await root.text().catch(() => '')).includes('httpd.js')) return { bidi: true, Browser: 'Firefox (BiDi)' };
}
return null;
} catch {
return null;
}
}
async function connect(port) {
const info = await probePort(port);
if (!info) throw new Error(`no DevTools endpoint on port ${port}`);
const ws = new WebSocket(info.bidi ? `ws://127.0.0.1:${port}/session` : info.webSocketDebuggerUrl);
await new Promise((resolve, reject) => {
ws.addEventListener('open', resolve, { once: true });
ws.addEventListener('error', () => reject(new Error('DevTools WebSocket connect failed')), { once: true });
setTimeout(() => reject(new Error('DevTools WebSocket open timeout')), 10000);
});
ws.addEventListener('message', (e) => onMessage(typeof e.data === 'string' ? e.data : String(e.data)));
return { ws, info };
}
/* ── WebDriver BiDi adapter (Firefox speaks BiDi, not CDP, on its debug port).
* Only the dialect changes: every call the kit makes maps 1:1 onto a BiDi
* command, and responses are rewritten back into CDP shapes so the rest of
* the kit never learns which engine is underneath. */
function decr(v) {
if (!v || typeof v !== 'object') return v;
switch (v.type) {
case 'undefined': case 'null': return undefined;
case 'string': case 'number': case 'boolean': return v.value;
case 'bigint': return Number(v.value);
case 'array': return (v.value || []).map(decr);
case 'object': { const o = {}; for (const [k, val] of v.value || []) o[k] = decr(val); return o; }
default: return v.value ?? null;
}
}
function bidiCall(m, p) {
const { ws } = requireSession();
const id = nextId++;
return new Promise((resolve, reject) => {
const timer = setTimeout(() => { pending.delete(id); reject(new Error(`BiDi timeout: ${m}`)); }, 30000);
pending.set(id, { resolve, reject, timer });
ws.send(JSON.stringify({ id, method: m, params: p || {} }));
});
}
const KEYBI = { Enter: '\uE006', Tab: '\uE004', Space: ' ', Backspace: '\uE003', Escape: '\uE00C', Delete: '\uE017', Insert: '\uE016', PageUp: '\uE00E', PageDown: '\uE00F', ArrowUp: '\uE013', ArrowDown: '\uE015', ArrowLeft: '\uE012', ArrowRight: '\uE014', Home: '\uE010', End: '\uE011', Shift: '\uE008', Control: '\uE009', Alt: '\uE00A' };
// Named keys (Enter/Delete/…) must win over their one-character text form: a
// "keyDown" value of '\r' is not the Enter key in WebDriver BiDi, and named keys
// like Delete have no text at all. Character keys fall back to the typed text.
const keyVal = (params) => {
const named = KEYBI[params.code || params.key];
if (named) return named;
if (typeof params.text === 'string' && params.text.length === 1 && params.text !== '\r') return params.text;
if (typeof params.code === 'string' && /^Key[A-Z]$/.test(params.code)) return params.code.slice(3).toLowerCase();
if (typeof params.code === 'string' && /^Digit[0-9]$/.test(params.code)) return params.code.slice(5);
return typeof params.key === 'string' ? params.key : ' ';
};
async function bidiSend(method, params, sid) {
const ctx = sid ?? session.context;
const pointer = (label, actions) => bidiCall('input.performActions', { context: ctx, actions: [{ type: label, id: label === 'key' ? 'k' : 'm', ...(label === 'pointer' ? { parameters: { pointerType: 'mouse' } } : {}), actions }] });
switch (method) {
case 'Page.enable': await bidiCall('session.subscribe', { events: ['browsingContext.load', 'browsingContext.domContentLoaded'] }); return {};
case 'Page.disable': return {};
case 'Page.bringToFront': try { await bidiCall('browsingContext.activate', { context: ctx }); } catch { /* detached? */ } return {};
case 'Page.navigate': await bidiCall('browsingContext.navigate', { url: params.url, context: ctx }); return {};
case 'Page.captureScreenshot': {
// Firefox builds vary: newer clip wants {type:'box',…}, format may be
// omitted (png default). Try plain, then legacy, then explicit shapes.
const base = { context: ctx, ...(params.clip ? { clip: { type: 'box', ...params.clip, scale: params.clip.scale ?? 1 } } : {}) };
let lastErr;
for (const shape of [base, { ...base, format: 'png' }, { context: ctx }, { context: ctx, format: 'png' }]) {
try { return await bidiCall('browsingContext.captureScreenshot', shape); } catch (e) { lastErr = e; }
}
throw lastErr;
}
case 'Target.getTargets': {
const r = await bidiCall('browsingContext.getTree', {});
return { targetInfos: (r.contexts || []).map((c) => ({ targetId: c.context, url: c.url || '', title: '', type: 'page' })) };
}
case 'Target.attachToTarget': session.context = params.targetId; return { sessionId: params.targetId };
case 'Target.createTarget': {
// Firefox's browsingContext.create ignores an inline URL: create the tab
// first and navigate it explicitly, then wait for the load to settle.
const wanted = typeof params.url === 'string' && params.url ? params.url : 'about:blank';
const r = await bidiCall('browsingContext.create', { type: 'tab' });
if (wanted !== 'about:blank') {
try { await bidiCall('browsingContext.navigate', { url: wanted, context: r.context, wait: 'complete' }); } catch { /* about:blank tab is usable */ }
}
return { targetId: r.context };
}
case 'Target.closeTarget': await bidiCall('browsingContext.close', { context: params.targetId }); return {};
case 'Runtime.evaluate': {
// Firefox's remote agent reads the draft-style `expression` param; the
// BiDi standard name rides along for other implementations.
const r = await bidiCall('script.evaluate', {
expression: params.expression,
functionDeclaration: `async function() { return eval(${JSON.stringify(params.expression)}); }`,
awaitPromise: true,
target: { context: ctx },
});
if (r.exceptionDetails) return { exceptionDetails: { text: r.exceptionDetails.text || JSON.stringify(r.exceptionDetails.stacktrace || {}) } };
return { result: { value: decr(r.result) } };
}
// Firefox rejects the draft `{type:'text'}` key action; type by dispatching
// one keyDown/keyUp pair per code point (real input events, keeps focus and
// selection behaviour), which is what BiDi actually supports.
case 'Input.insertText': {
const acts = [];
for (const ch of [...String(params.text)]) {
const value = ch === '\n' ? '\r' : ch;
acts.push({ type: 'keyDown', value }, { type: 'keyUp', value });
}
if (acts.length) await pointer('key', acts);
return {};
}
case 'Input.dispatchKeyEvent': {
const v = keyVal(params);
const acts = params.type === 'keyUp' ? [{ type: 'keyUp', value: v }] : params.type === 'keyDown' ? [{ type: 'keyDown', value: v }, { type: 'keyUp', value: v }] : [{ type: 'keyDown', value: v }];
await pointer('key', acts); return {};
}
case 'Input.dispatchMouseEvent': {
const acts = [];
if (params.type === 'mouseMoved' || params.type === 'mousePressed') acts.push({ type: 'pointerMove', x: params.x, y: params.y, duration: 10 });
if (params.type === 'mousePressed') acts.push({ type: 'pointerDown', button: 0 });
if (params.type === 'mouseReleased') acts.push({ type: 'pointerUp', x: params.x, y: params.y, button: 0 });
await pointer('pointer', acts); return {};
}
case 'session.end': try { await bidiCall('session.end', {}); } catch { /* no session */ } return {};
case 'Browser.close': try { await bidiCall('browser.close', {}); } catch { /* browser gone */ } return {};
default: return {};
}
}
async function pageTargets() {
const { targetInfos } = await send('Target.getTargets', {}, null);
return targetInfos.filter((t) => t.type === 'page' && !t.url.startsWith('devtools://'));
}
async function attachTo(targetId) {
const prev = session.sessionId;
const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true }, null);
session.sessionId = sessionId;
session.targetId = targetId;
if (prev !== sessionId) await send('Page.enable', {});
}
async function attachToPage() {
const pages = await pageTargets();
if (!pages.length) {
const created = await send('Target.createTarget', { url: 'about:blank' }, null);
await attachTo(created.targetId);
return;
}
await attachTo(pages[0].targetId);
}
async function evaluate(expression) {
const r = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });
if (r.exceptionDetails) throw new Error(`page script error: ${r.exceptionDetails.text}`);
return r.result?.value;
}
async function waitForLoad(timeoutMs = 15000) {
const loaded = new Promise((resolve) => {
let done = false, poll = null;
const finish = (how) => {
if (done) return;
done = true;
clearTimeout(timer);
clearInterval(poll);
eventHooks.delete(hook);
resolve(how);
};
const hook = (msg) => {
if (msg.method === 'Page.loadEventFired' && msg.sessionId === session?.sessionId) finish('load');
};
eventHooks.add(hook);
const timer = setTimeout(() => finish('timeout'), timeoutMs);
// BiDi (Firefox) can fire the load event before a freshly created tab is
// attached/subscribed, so an event-only wait misses it and burns the whole
// timeout (newTab took ~15 s before this). Poll the document state as a
// fast second signal.
poll = setInterval(async () => {
if (session?.engine !== 'bidi' || done) return;
try { if ((await evaluate('document.readyState')) === 'complete') finish('readyState'); } catch { /* navigating */ }
}, 250);
});
const how = await loaded;
await new Promise((r) => setTimeout(r, 400)); // settle for hydration
const ready = await evaluate('document.readyState').catch(() => 'unknown');
return { loadEvent: how, readyState: ready };
}
async function waitForPort(port, timeoutMs) {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (await probePort(port)) return true;
await new Promise((r) => setTimeout(r, 400));
}
return false;
}
async function findEdge(explicit, kind = 'edge') {
const cand = BROWSER_CANDIDATES[kind] || BROWSER_CANDIDATES.edge;
for (const p of [explicit, ...cand]) {
if (!p) continue;
try { await fs.access(p); return p; } catch { /* next */ }
}
return null;
}
async function bidiHandshake() {
// Firefox's BiDi (remote agent) requires a real WebDriver session:
// session.status answers, but commands only work after session.new
// with capabilities — empirically probed against Firefox 158.
await bidiCall('session.status', {});
let r;
try {
r = await bidiCall('session.new', { capabilities: { alwaysMatch: {}, firstMatch: [{}] } });
} catch (e) {
// Firefox allows one BiDi session; a previous detach or another client can
// hold it, and a bare WebSocket close does not release it.
if (/Maximum number of active sessions/i.test(String((e && e.message) || ''))) {
throw new Error('Firefox already has an active WebDriver BiDi session (a previous detach or another client left it behind). Restart that Firefox instance, then retry.');
}
throw e;
}
session.bidiSessionId = r && r.sessionId;
session.bidiReady = true;
}
async function attachOnly(port) {
const { ws, info } = await connect(port);
session = { ws, port, child: null, headless: null, profileDir: null, attached: true, kind: 'unknown', engine: info.bidi ? 'bidi' : 'cdp' };
try {
await attachToPage();
} catch (error) {
// Never leave a half-attached session behind: status would report
// running:true with no active tab for every later call.
try { ws.close(); } catch { /* already gone */ }
session = null;
throw error;
}
}
async function doLaunch(args) {
const port = effectivePort(args);
if (session && session.port === port && session.ws.readyState === 1) {
return { ok: true, note: 'already running', port: session.port };
}
if (await probePort(port)) {
await attachOnly(port);
return { ok: true, attached: true, note: `attached to the browser already listening on ${port} (live mode)`, port };
}
const wantedKind = String(args.browser || cfgVal('browser', 'edge')).toLowerCase();
const explicit = args.executablePath || cfgVal('executablePath', '') || undefined;
const executable = await findEdge(explicit, explicit ? kindOf(explicit) : wantedKind);
if (!executable) throw new Error(`${wantedKind} not found; pass executablePath.`);
const kind = kindOf(executable);
const useReal = args.realProfile ?? cfgVal('realProfile', true);
const realFor = kind === 'edge' ? REAL_PROFILE : kind === 'chrome' ? CHROME_REAL_PROFILE : await ffDefaultProfile();
const kitDir = kind === 'edge' ? KIT_PROFILE : `${KIT_PROFILE}-${kind}`;
const profileDir = typeof args.profileDir === 'string' && args.profileDir
? args.profileDir
: (useReal && realFor ? realFor : cfgVal('profileDir', '') || kitDir);
await fs.mkdir(profileDir, { recursive: true });
const headless = args.headless ?? cfgVal('headless', false);
const proxyFlag = await launchProxyFlag(args);
// The kit owns browser proxy state entirely: a system/v2ray proxy never
// leaks into the launched browser, and a proxy-less launch is explicit
// about going direct (--no-proxy-server / network.proxy.type=0).
const childEnv = { ...process.env };
for (const k of ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy']) delete childEnv[k];
const child = spawn(executable, kind === 'firefox' ? [
`-remote-debugging-port=${port}`,
'-profile', profileDir,
'-no-remote',
...(headless ? ['-headless'] : []),
// Firefox's -proxy-server takes host:port, not an http:// URL; a
// proxy-less launch states direct traffic explicitly (network.proxy.type=0).
...(proxyFlag ? ['-proxy-server', proxyFlag.replace(/^https?:\/\//, '')] : ['-preferences', '{"network.proxy.type":0}']),
'about:blank',
] : [
`--remote-debugging-port=${port}`,
`--user-data-dir=${profileDir}`,
'--no-first-run',
'--no-default-browser-check',
// Server/console sessions treat windows as occluded and stop painting,
// which starves surface-based screenshots and throttles timers.
'--disable-features=CalculateNativeWinOcclusion',
'--disable-backgrounding-occluded-windows',
'--disable-renderer-backgrounding',
...(headless ? ['--headless=new'] : []),
...(proxyFlag ? [`--proxy-server=${proxyFlag}`] : ['--no-proxy-server']),
'about:blank',
], { stdio: 'ignore', detached: false, env: childEnv });
if (!(await waitForPort(port, 25000))) {
child.kill();
throw new Error('browser started but the DevTools port never opened. If your everyday browser is running without a debug port it owns this profile: pass relaunch:true (closes it and reopens it debuggable), or use a different profileDir.');
}
const { ws, info } = await connect(port);
session = { ws, port, child, headless, profileDir, attached: false, kind, engine: info.bidi ? 'bidi' : 'cdp', launchArgs: { browser: kind, executablePath: executable, profileDir, headless, port } };
await attachToPage();
return { ok: true, launched: true, headless, port, profileDir, realProfile: profileDir === realFor, browser: kind, executable };
}
async function ensureActive(args) {
if (session && session.ws.readyState === 1) return;
const port = effectivePort(args);
if (await probePort(port)) {
await attachOnly(port);
return;
}
await doLaunch(args ?? {});
}
/* ── Proxy engine: routes all browser traffic (including the web seam) through
* free proxies. One hop is handed straight to the browser; two or more chain
* through an in-kit local CONNECT forwarder (browser → 127.0.0.1 → hop1 →
* hop2 → … → origin). Candidates are verified by fetching an IP echo through
* them, so "working" means the exit IP literally proves the route. */
const parseProxy = (s) => {
const m = /^(?:https?:\/\/)?([\w.-]+):(\d{1,5})$/.exec(String(s).trim());
return m ? { host: m[1], port: Number(m[2]) } : null;
};
const chainLabel = (h) => `${h.host}:${h.port}`;
let chainHolder = null; // multi-hop mode: { hops, server, endpoint, raw }
let activeProxy = null; // single-hop mode: 'host:port' given to the browser
function netConnect(host, port, timeoutMs) {
return new Promise((resolve, reject) => {
const s = net.connect({ host, port });
const t = setTimeout(() => { s.destroy(); reject(new Error(`connect ${host}:${port} timeout`)); }, timeoutMs);
s.once('connect', () => { clearTimeout(t); resolve(s); });
s.once('error', (e) => { clearTimeout(t); reject(e); });
});
}
function hopConnect200(sock, carry, host, port, timeoutMs) {
return new Promise((resolve) => {
let buf = carry || '';
const cleanup = () => { clearTimeout(timer); sock.removeListener('data', onData); sock.removeListener('error', onError); };
const timer = setTimeout(() => { cleanup(); resolve({ ok: false, rest: '', reason: 'timeout' }); }, timeoutMs);
const onData = (d) => {
buf += d.toString('latin1');
const i = buf.indexOf('\r\n\r\n');
if (i < 0) { if (buf.length > 16384) { cleanup(); resolve({ ok: false, rest: '', reason: 'bad headers' }); } return; }
cleanup();
const m = /^HTTP\/1\.[01] (\d{3})/.exec(buf);
resolve({ ok: !!m && m[1] === '200', rest: buf.slice(i + 4), reason: m ? `status ${m[1]}` : 'not http' });
};
const onError = () => { cleanup(); resolve({ ok: false, rest: '', reason: 'socket error' }); };
sock.on('data', onData);
sock.on('error', onError);
sock.write(`CONNECT ${host}:${port} HTTP/1.1\r\nHost: ${host}:${port}\r\nProxy-Connection: keep-alive\r\n\r\n`);
});
}
async function chainTunnel(hops, targetHost, targetPort, timeoutMs = 9000) {
const sock = await netConnect(hops[0].host, hops[0].port, timeoutMs);
let carry = '';
for (const [th, tp] of [...hops.slice(1).map((h) => [h.host, h.port]), [targetHost, targetPort]]) {
const r = await hopConnect200(sock, carry, th, tp, timeoutMs);
carry = '';
if (!r.ok) { sock.destroy(); throw new Error(`proxy ${chainLabel(hops[0])}: CONNECT ${th}:${tp} -> ${r.reason}`); }
carry = r.rest;
}
return { sock, carry };
}
async function proxyHttpGet(hops, url, timeoutMs = 9000) {
const m = /^https?:\/\/([^/:]+)(?::(\d+))?(\/[^\s]*)?$/i.exec(url);
if (!m) throw new Error('bad proxy-probe url');
const host = m[1];
const port = m[2] ? Number(m[2]) : 80;
const path = m[3] || '/';
const direct = hops.length === 1 && port === 80;
let sock, carry = '';
if (direct) sock = await netConnect(hops[0].host, hops[0].port, timeoutMs);
else ({ sock, carry } = await chainTunnel(hops, host, port, timeoutMs));
return await new Promise((resolve, reject) => {
let buf = '';
const fin = (err) => {
if (done) return; done = true;
if (err) { sock.destroy(); reject(err); return; }
const im = /^HTTP\/1\.[01] (\d{3})/.exec(buf);
const bi = buf.indexOf('\r\n\r\n');
resolve({ status: im ? Number(im[1]) : 0, body: (bi >= 0 ? buf.slice(bi + 4) : buf).trim().split(/\r?\n/)[0] });
};
let done = false;
sock.setTimeout(timeoutMs, () => fin(new Error('proxy read timeout')));
sock.on('data', (d) => { buf += d.toString('latin1'); });
sock.on('end', () => fin()); sock.on('close', () => fin()); sock.on('error', (e) => fin(e));
// Single hop over http: absolute-form forward GET — every HTTP proxy does
// this, including the free ones that refuse CONNECT (common on IR lists).
// Chaining uses the CONNECT nesting chainTunnel speaks.
sock.write(`${direct ? `GET ${url}` : `GET ${path}`} HTTP/1.1\r\nHost: ${host}\r\nUser-Agent: edge-kit/3.6\r\nAccept: */*\r\nConnection: close\r\n\r\n`);
if (carry) sock.write(Buffer.from(carry, 'latin1'));
});
}
const ECHOES = ['http://checkip.amazonaws.com/', 'http://ifconfig.me/ip', 'http://ipinfo.io/json'];
async function echoLadder(hops) {
// Free proxies share exit IPs, so any one echo service can rate-limit (429);
// the ladder keeps verification honest as long as one echo answers.
for (const url of ECHOES) {
try {
const r = await proxyHttpGet(hops, url);
if (r.status !== 200) continue;
let ip = null, country = null, org = null;
try { const j = JSON.parse(r.body); ip = j.ip; country = j.country; org = j.org; } catch { if (/^[0-9a-fA-F:.]{4,45}$/.test(r.body)) ip = r.body; }
if (ip) return { ip, country, org };
} catch { /* next echo */ }
}
return null;
}
let directEgress;
async function directEgressOf() {
// node fetch never reads HTTP_PROXY/v2ray — this is the machine's true exit.
if (directEgress === undefined) {
directEgress = null;
try { const r = await fetch('http://checkip.amazonaws.com/', { signal: AbortSignal.timeout(7000) }); directEgress = (await r.text()).trim().split(/\s/)[0] || null; } catch { /* offline */ }
}
return directEgress;
}
async function probeCandidate(h) {
const t0 = Date.now();
const [e, own] = await Promise.all([echoLadder([h]), directEgressOf()]);
if (!e) return { ok: false, reason: 'no echo (dead or blocking)', ms: Date.now() - t0 };
if (own && (e.ip === own || e.ip.startsWith(own.split('.').slice(0, 2).join('.') + '.'))) {
return { ok: false, reason: `transparent (exit ${e.ip} is your own network — routing through it changes nothing)`, ms: Date.now() - t0 };
}
return { ok: true, ip: e.ip, country: e.country, as: e.org, ms: Date.now() - t0 };
}
const pipeBoth = (a, b) => {
a.on('data', (c) => { if (!b.write(c)) a.pause(); });
b.on('drain', () => a.resume());
a.on('end', () => { try { b.end(); } catch { /* gone */ } });
a.on('error', () => { try { b.destroy(); } catch { /* gone */ } });
a.on('close', () => { try { b.destroy(); } catch { /* gone */ } });
};
function startChainServer(hops) {
return new Promise((resolve, reject) => {
const server = net.createServer((client) => {
client.on('error', () => { try { client.destroy(); } catch { /* gone */ } });
let buf = '';
const onData = (d) => {
buf += d.toString('latin1');
const i = buf.indexOf('\r\n\r\n');
if (i < 0) { if (buf.length > 65536) client.destroy(); return; }
client.removeListener('data', onData);
// A dead proxy hop makes chainTunnel throw inside handle(). Never leave
// that rejection floating: it surfaces as an unhandledRejection and the
// DSH host treats plugin errors as fatal load failures (crash 2026-11-08
// 20:31: proxy 34.43.46.91:80 CONNECT -> 503 took the whole host down).
// Fail only this browser connection instead.
void handle(client, buf.slice(0, i), buf.slice(i + 4)).catch(() => {
try { client.write('HTTP/1.1 502 Bad Gateway\r\nProxy-Chain: tunnel failed\r\nContent-Length: 0\r\nConnection: close\r\n\r\n'); } catch { /* gone */ }
try { client.destroy(); } catch { /* gone */ }
});
};
client.on('data', onData);
});
const handle = async (client, head, rest) => {
const [method, target] = head.split('\r\n')[0].split(' ');
let host, port, rewritten = null;
if (method === 'CONNECT') {
const p = target.split(':'); host = p[0]; port = Number(p[1]);
if (!host || !port) throw new Error('bad CONNECT target');
} else {
const m = /^(?:https?:)?\/\/([^/:?#]+)(?::(\d+))?(\/[^\s]*)?/i.exec(target) || /^(?:https?:)?\/\/([^/:?#]+)(?::(\d+))?$/i.exec(target);
if (!m) throw new Error('bad forward target');
host = m[1]; port = m[2] ? Number(m[2]) : 80;
rewritten = `${method} ${m[3] || '/'} HTTP/1.1${head.slice(head.indexOf('\r\n'))}\r\n\r\n`;
}
const { sock, carry } = await chainTunnel(hops, host, port, 10000);
client.write('HTTP/1.1 200 Connection Established\r\n\r\n');
if (rewritten) sock.write(Buffer.concat([Buffer.from(rewritten, 'latin1'), Buffer.from(rest, 'latin1')]));
else if (carry) sock.write(Buffer.from(carry, 'latin1'));
pipeBoth(client, sock); pipeBoth(sock, client);
};
server.on('error', reject);
server.listen(0, '127.0.0.1', () => resolve(server));
});
}
const stopChain = () => {
if (chainHolder) { try { chainHolder.server.close(); } catch { /* gone */ } chainHolder = null; }
};
async function ensureHolder(hops) {
stopChain(); activeProxy = null;
if (hops.length < 2) { activeProxy = chainLabel(hops[0]); return null; }
const server = await startChainServer(hops);
chainHolder = { hops, server, mode: 'chain', raw: hops.map(chainLabel).join(','), endpoint: `http://127.0.0.1:${server.address().port}` };
return chainHolder;
}
async function launchProxyFlag(args) {
if (chainHolder) return chainHolder.endpoint;
if (activeProxy) return `http://${activeProxy}`;
const raw = typeof args.proxyChain === 'string' && args.proxyChain.trim()
? args.proxyChain.trim()
: String(cfgVal('proxyChain', '') || '').trim();
if (!raw) return null;
const hops = raw.split(',').map(parseProxy).filter(Boolean);
if (!hops.length) return null;
const held = await ensureHolder(hops);
return held ? held.endpoint : `http://${activeProxy}`;
}
const activeProxyView = () => chainHolder
? { chain: chainHolder.hops.map(chainLabel), mode: 'chain', endpoint: chainHolder.endpoint }
: (activeProxy ? { chain: [activeProxy], mode: 'single' } : null);
async function egressVia(hops) {
const t0 = Date.now();
const e = await echoLadder(hops);
return e ? { ok: true, ip: e.ip, country: e.country, as: e.org, ms: Date.now() - t0 } : { ok: false, error: 'no echo back', ms: Date.now() - t0 };
}
async function restartSession() {
const la = session && session.launchArgs ? session.launchArgs : null;
if (!session || session.attached || !la) return false;
const { child, ws, engine, kind } = session;
// Close the browser itself before dropping the socket: for Firefox the spawn
// handle is only the Windows launcher, so killing it can orphan the browser
// and leave Firefox's single BiDi session registered (the next session.new
// then fails with "Maximum number of active sessions").
try { ws.send(JSON.stringify({ id: nextId++, method: engine === 'bidi' ? 'browser.close' : 'Browser.close', params: {} })); } catch { /* gone */ }
await new Promise((r) => setTimeout(r, 300));
session = null;
try { ws.close(); } catch { /* gone */ }
if (child && child.exitCode === null) child.kill();
const port = la.port || effectivePort(la);
const waitFree = async (ms) => {
const t0 = Date.now();
while (await probePort(port) && Date.now() - t0 < ms) await new Promise((r) => setTimeout(r, 400));
return !(await probePort(port));
};
if (!(await waitFree(6000))) {
// A survivor browser (Edge startup-boost, profile handoff, leftover window)
// retook the port without our new flags — a fresh spawn would merge into it
// and silently lose proxy routing. For Chromium, kill instances of this
// browser kind (same semantics as relaunch:true; logins survive, windows
// reopen). Firefox refuses: taskkill would close every Firefox window.
if (kind === 'firefox') return false;
const exe = kind === 'chrome' ? 'chrome' : 'msedge';
const killCmd = process.platform === 'win32' ? `taskkill /IM ${exe}.exe /F` : `pkill -9 -x ${exe}`;
await new Promise((r) => exec(killCmd, () => r()));
if (!(await waitFree(8000))) return false;
}
await doLaunch(la);
return true;
}
async function mouseClick(x, y, clickCount = 1) {
for (const type of ['mousePressed', 'mouseReleased']) {
await send('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount, buttons: type === 'mousePressed' ? 1 : 0 }, session.sessionId);
}
}
async function mouseDrag(fromX, fromY, toX, toY, steps = 12) {
await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: fromX, y: fromY }, session.sessionId);
await send('Input.dispatchMouseEvent', { type: 'mousePressed', x: fromX, y: fromY, button: 'left', clickCount: 1, buttons: 1 }, session.sessionId);
for (let i = 1; i <= steps; i++) {
await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: fromX + (toX - fromX) * i / steps, y: fromY + (toY - fromY) * i / steps, button: 'left', buttons: 1 }, session.sessionId);
await new Promise((r) => setTimeout(r, 16));
}
await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: toX, y: toY, button: 'left', clickCount: 1 }, session.sessionId);
}
const KEYCODES = {
Enter: [13, 13], Tab: [9, 9], Escape: [27, 27], Space: [32, 32], Backspace: [8, 8], Delete: [46, 46],
ArrowLeft: [37, 37], ArrowUp: [38, 38], ArrowRight: [39, 39], ArrowDown: [40, 40],
Home: [36, 36], End: [35, 35], PageUp: [33, 33], PageDown: [34, 34],
Shift: [16, 16], Control: [17, 17], Alt: [18, 18],
};
for (let c = 0; c < 26; c++) KEYCODES['Key' + String.fromCharCode(65 + c)] = [65 + c, 65 + c];
for (let d = 0; d < 10; d++) KEYCODES['Digit' + d] = [48 + d, 48 + d];
async function pressKey(key, times = 1) {
// Normalize the requested key: named keys are case-insensitive ("Space" and
// "space" are the same key), and the character-carrying keys (Space, Enter)
// must carry their real character in `key`/`text` — CDP otherwise reports an
// empty event.key for the named form and games/forms never see the key.
const requested = String(key);
const named = Object.keys(KEYCODES).find((candidate) => candidate.toLowerCase() === requested.toLowerCase());
const keyName = named || requested;
const vk = KEYCODES[keyName] || [requested.length === 1 ? requested.toUpperCase().charCodeAt(0) : 0, 0];
const code = KEYCODES[keyName] ? keyName : (requested.length === 1 ? `Key${requested.toUpperCase()}` : '');
const char = keyName === 'Space' ? ' ' : keyName === 'Enter' ? '\r' : (requested.length === 1 ? requested : undefined);
const base = { key: keyName === 'Space' ? ' ' : keyName, code, windowsVirtualKeyCode: vk[0], nativeVirtualKeyCode: vk[1] };
for (let i = 0; i < times; i++) {
await send('Input.dispatchKeyEvent', { type: char !== undefined ? 'keyDown' : 'rawKeyDown', ...base, ...(char !== undefined ? { text: char } : {}) }, session.sessionId);
await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base }, session.sessionId).catch(async () => {
await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base }, session.sessionId);
});
if (times > 1) await new Promise((r) => setTimeout(r, 90));
}
}
async function captureShot(saveTo, clip) {
await send('Page.bringToFront', {}).catch(() => {});
const params = { format: 'png', fromSurface: false };
if (clip) params.clip = { ...clip, scale: 1 };
let data;
try {
({ data } = await send('Page.captureScreenshot', params));
} catch {
({ data } = await send('Page.captureScreenshot', { format: 'png', ...(clip ? { clip: { ...clip, scale: 1 } } : {}) }));
}
const buffer = Buffer.from(data, 'base64');
const file = saveTo || path.join(os.tmpdir(), `edge-kit-shot-${Date.now()}.png`);
await fs.mkdir(path.dirname(file), { recursive: true });
await fs.writeFile(file, buffer);
return { path: file, bytes: buffer.length };
}
/** Shared in-page walker: shadow-piercing visibility, naming, and element catalog. */
const WALKER = `
const vis = (el) => { const r = el.getBoundingClientRect(); if (r.width < 4 || r.height < 4) return null;
try { const cs = getComputedStyle(el); if (cs.visibility === 'hidden' || cs.display === 'none' || cs.opacity === '0') return null; } catch { }
return r; };
const clean = (s) => String(s || '').replace(/\\s+/g, ' ').trim();
const nameOf = (el) => clean(el.getAttribute('aria-label')).slice(0, 70)
|| clean(el.innerText).slice(0, 70) || clean(el.getAttribute('placeholder'))
|| clean(el.getAttribute('title')) || clean(el.getAttribute('alt')) || clean(el.value) || '';
const isInter = (el) => {
const tag = el.tagName.toLowerCase(); const role = (el.getAttribute('role') || '').toLowerCase();
if (['button', 'summary'].includes(tag)) return true;
if (tag === 'a' && el.hasAttribute('href')) return true;
if (['input', 'textarea', 'select'].includes(tag) && el.type !== 'hidden') return true;
if (el.isContentEditable) return true;
return ['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'combobox', 'menuitem', 'tab', 'option'].includes(role);
};
`;
async function seeOnce(opts = {}) {
const js = `(async () => {
${WALKER}
const els = []; const seen = new Set();
function walk(root) {
for (const el of root.querySelectorAll('*')) {
if (el.shadowRoot) walk(el.shadowRoot);
if (!isInter(el)) continue;
const r = vis(el); if (!r) continue;
const name = nameOf(el);
const tag = el.tagName.toLowerCase();
const key = tag + '|' + (el.getAttribute('role') || '') + '|' + name;
if (seen.has(key)) continue; seen.add(key);
els.push({ role: (el.getAttribute('role') || (tag === 'a' ? 'link' : tag)), name,
x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2), el });
if (els.length >= 60) return;
}
}
walk(document);
let text = document.body ? clean(document.body.innerText) : '';
function xt(root) { for (const el of root.querySelectorAll('*')) { if (el.shadowRoot) { text += ' ' + clean(el.shadowRoot.textContent); xt(el.shadowRoot); } } }
xt(document);
const dialogs = [];
function dwalk(root) {
for (const el of root.querySelectorAll('[role="dialog"],[role="alertdialog"],dialog')) {
if (el.shadowRoot) dwalk(el.shadowRoot);
const r = vis(el); if (!r) continue;
dialogs.push(clean(el.innerText).slice(0, 160));
}
}
dwalk(document);
// Keep the live element references from this see so click{index} can
// re-resolve its row after scrolling or DOM movement instead of firing at a
// stale, cached coordinate (which silently no-ops on a moved page).
try { window.__edgeKitElements = els.map((entry) => entry.el); } catch { }
return { url: location.href, title: document.title,
text: text.slice(0, ${Math.min(opts.maxText ?? cfgVal('seeTextCap', 2200), 6000)}),
elements: els.map(({ role, name, x, y }) => ({ role, name, x, y })), dialogs: [...new Set(dialogs)].slice(0, 4) };
})()`;
return evaluate(js);
}
async function findByName(needle) {
const js = `(() => {
${WALKER}
const want = ${JSON.stringify(String(needle).toLowerCase())};
let best = null;
function walk(root) {
for (const el of root.querySelectorAll('*')) {
if (el.shadowRoot) walk(el.shadowRoot);
if (!isInter(el) && !el.matches('a,button,input,textarea,select,summary,[role],[jsaction],[contenteditable]')) continue;
const label = nameOf(el).toLowerCase();
if (!label.includes(want)) continue;
const r = vis(el); if (!r) continue;
const score = (label === want ? 0 : label.startsWith(want) ? 1 : 2) + (isInter(el) ? 0 : 5);
if (!best || score < best.score) best = { score, x: r.x + r.width / 2, y: r.y + r.height / 2, name: nameOf(el) };
}
}
walk(document);
return best;
})()`;
return evaluate(js);
}
async function focusField(by) {
const js = `(() => {
${WALKER}
const want = ${JSON.stringify(String(by).toLowerCase())};
const labelOf = (el) => {
const names = [el.getAttribute('aria-label'), el.getAttribute('placeholder'), el.getAttribute('title'), el.name || null];
if (el.labels) for (const l of el.labels) names.push(l.innerText);
if (el.id) { const l = document.querySelector('label[for="' + el.id + '"]'); if (l) names.push(l.innerText); }
return names.map(clean).filter(Boolean).join(' ').toLowerCase();
};
let best = null;
function walk(root) {
for (const el of root.querySelectorAll('*')) {
if (el.shadowRoot) walk(el.shadowRoot);
if (!el.matches('input,textarea,select,[contenteditable="true"]')) continue;
if (el.type === 'hidden' || el.disabled) continue;
const hay = labelOf(el);
if (!hay.includes(want)) continue;
const r = vis(el); if (!r) continue;
const score = hay === want ? 0 : 1;
if (!best || score < best.score) best = { score, el };
}
}
walk(document);
if (!best) return null;
best.el.scrollIntoView({ block: 'center' });
best.el.focus();
return document.activeElement === best.el ? nameOf(best.el) || ${JSON.stringify(by)} : 'focused-by-invoke';
})()`;
return evaluate(js);
}
async function pageInfo() {
return { url: await evaluate('location.href').catch(() => null), title: await evaluate('document.title').catch(() => null) };
}
async function run(args) {
const action = typeof args?.action === 'string' ? args.action : 'status';
switch (action) {
case 'launch': {
if (args.relaunch) {
// Take over a profile-owning browser we do not control (or do): close
// its instances, then spawn a fresh debuggable one. Session restore
// brings the user's tabs back on the reopened browser. Only the engine
// being relaunched is touched, and Firefox refuses outright because
// taskkill would close every Firefox window the user has open.
const relKind = args.executablePath ? kindOf(args.executablePath) : String(args.browser || cfgVal('browser', 'edge')).toLowerCase();
if (relKind === 'firefox') throw new Error('relaunch is not supported for Firefox: it would kill every Firefox window. Use an isolated profileDir, or close that Firefox yourself.');
try { session?.ws?.close(); } catch { /* gone */ }
session = null;
await new Promise((res) => exec(`taskkill /IM ${relKind === 'chrome' ? 'chrome.exe' : 'msedge.exe'} /F`, () => res()));
await new Promise((r) => setTimeout(r, 1800));
}
return doLaunch(args);
}
case 'attach': {
const port = effectivePort(args);
// Firefox allows exactly one WebDriver BiDi session. Re-attaching to a
// browser this process already drives would open a second socket against
// that single session, fail the handshake, and strand the browser with no
// owner (neither relaunch nor close could reach it). Report the existing
// connection instead.
if (session && session.port === port && session.ws.readyState === 1) {
return { ok: true, attached: true, port, liveMode: !!session.attached, alreadyConnected: true, note: 'already connected to this browser in this process' };
}
await attachOnly(port);
return { ok: true, attached: true, port, liveMode: true };
}
case 'status': {
const settings = settingsSnapshot();
if (session && session.ws.readyState === 1) {
return { ok: true, running: true, liveMode: session.attached, port: session.port, headless: session.headless, childPid: session.child?.pid ?? null, profileDir: session.profileDir, proxy: activeProxyView(), settings, ...await pageInfo() };
}
const occupied = !!(await probePort(effectivePort(args)));
return { ok: true, running: false, portOccupied: occupied, settings };
}
case 'tabs': {
await ensureActive(args);
const pages = await pageTargets();
return { ok: true, current: session.targetId, tabs: pages.map((t, i) => ({ i, targetId: t.targetId, url: t.url, title: t.title, current: t.targetId === session.targetId })) };
}
case 'newTab': {
await ensureActive(args);
const { targetId } = await send('Target.createTarget', { url: typeof args.url === 'string' ? args.url : 'about:blank' }, null);
await attachTo(targetId);
if (typeof args.url === 'string' && args.url !== 'about:blank') await waitForLoad();
return { ok: true, ...await pageInfo() };
}
case 'switchTab': {
await ensureActive(args);
const pages = await pageTargets();
const t = Number.isInteger(args.index) ? pages[args.index] : pages.find((p) => p.targetId === args.targetId);
if (!t) return { ok: false, error: 'tab not found', tabs: pages.map((p, i) => ({ i, url: p.url })) };
await attachTo(t.targetId);
return { ok: true, ...await pageInfo() };
}
case 'closeTab': {
await ensureActive(args);
const pages = await pageTargets();
const t = Number.isInteger(args.index) ? pages[args.index] : pages.find((p) => p.targetId === args.targetId);
if (!t) return { ok: false, error: 'tab not found' };
await send('Target.closeTarget', { targetId: t.targetId }, null);
const rest = await pageTargets();
if (t.targetId === session.targetId) {
if (rest.length) await attachTo(rest[0].targetId);
else session = null;
}
return { ok: true, remaining: rest.length };
}
case 'goto': {
if (typeof args.url !== 'string' || !args.url) throw new Error('goto needs a url');
await ensureActive(args);
await send('Page.navigate', { url: args.url });
const load = await waitForLoad();
return { ok: true, ...await pageInfo(), ...load };
}
case 'back':
case 'forward':
case 'reload': {
await ensureActive(args);
const hist = action === 'back' ? 'history.back()' : action === 'forward' ? 'history.forward()' : 'location.reload()';
await evaluate(hist);
await waitForLoad().catch(() => ({}));
return { ok: true, ...await pageInfo() };
}
case 'see': {
await ensureActive(args);
const snap = await seeOnce(args);
lastElements = snap.elements.map((e) => ({ x: e.x, y: e.y, role: e.role, name: e.name }));
return { ok: true, url: snap.url, title: snap.title, text: snap.text, dialogs: snap.dialogs, elements: snap.elements.map((e, i) => ({ i, role: e.role, name: e.name })) };
}
case 'click': {
await ensureActive(args);
let point = null;
if (Number.isInteger(args.index)) {
const e = lastElements[args.index];
if (!e) return { ok: false, error: `no element #${args.index} in the last see; call see first` };
// Re-resolve the element captured by the most recent see: scroll it into
// view and measure it again, so a scrolled or re-laid-out page cannot
// turn the click into a silent miss at a stale coordinate.
point = await evaluate(`(() => {
const list = window.__edgeKitElements || [];
const el = list[${Number(args.index)}];
if (!el || !el.isConnected) return null;
el.scrollIntoView({ block: 'center' });
const r = el.getBoundingClientRect();
return { x: r.x + r.width / 2, y: r.y + r.height / 2, name: (el.innerText || el.getAttribute('aria-label') || '').trim().slice(0, 60) };
})()`);
if (!point) { lastElements = []; return { ok: false, error: `element #${args.index} from the last see is gone; call see again` }; }
} else if (typeof args.text === 'string' && args.text) {
point = await findByName(args.text);
} else if (typeof args.selector === 'string' && args.selector) {
point = await evaluate(`(() => { const el = document.querySelector(${JSON.stringify(args.selector)}); if (!el) return null; el.scrollIntoView({ block: 'center' }); const r = el.getBoundingClientRect(); return { x: r.x + r.width / 2, y: r.y + r.height / 2, name: (el.innerText || '').trim().slice(0, 60) }; })()`);
}
if (!point) return { ok: false, error: 'nothing matched; call see to list what is clickable' };
await mouseClick(point.x, point.y);
await new Promise((r) => setTimeout(r, 500));
return { ok: true, clicked: point.name || args.text || args.selector, ...await pageInfo() };
}
case 'type': {
await ensureActive(args);
if (typeof args.text !== 'string') throw new Error('type needs text');
if (args.selector) {
const ok = await evaluate(`(() => { const el = document.querySelector(${JSON.stringify(String(args.selector))}); if (!el) return false; el.scrollIntoView({ block: 'center' }); el.focus(); return document.activeElement === el; })()`);
if (!ok) return { ok: false, error: `selector not focusable: ${args.selector}` };
} else if (typeof args.into === 'string' && args.into) {
const label = await focusField(args.into);
if (!label) return { ok: false, error: `no field labeled like ${JSON.stringify(args.into)}; call see` };
}
await send('Input.insertText', { text: args.text }, session.sessionId);
if (args.submit === true) {
const base = { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 };
await send('Input.dispatchKeyEvent', { type: 'keyDown', ...base, text: '\r' }, session.sessionId);
await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base }, session.sessionId);
await waitForLoad().catch(() => ({}));
}
return { ok: true, typed: args.text.length, submitted: args.submit === true, ...await pageInfo() };
}
case 'press': {
await ensureActive(args);
const key = typeof args.key === 'string' ? args.key : 'Enter';
await pressKey(key, Math.min(Number.isInteger(args.times) ? args.times : 1, 50));
await new Promise((r) => setTimeout(r, 400));
return { ok: true, key, ...await pageInfo() };
}
case 'clickAt': {
await ensureActive(args);
const x = Number(args.x), y = Number(args.y);
if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error('clickAt needs numeric x and y');
await mouseClick(x, y);
await new Promise((r) => setTimeout(r, 300));
return { ok: true, clickedAt: { x, y }, ...await pageInfo() };
}
case 'drag': {
await ensureActive(args);
const x = Number(args.x), y = Number(args.y), toX = Number(args.toX), toY = Number(args.toY);
if (![x, y, toX, toY].every(Number.isFinite)) throw new Error('drag needs x, y, toX, toY');
await mouseDrag(x, y, toX, toY);
return { ok: true, dragged: { from: { x, y }, to: { x: toX, y: toY } }, ...await pageInfo() };
}
case 'video': {
await ensureActive(args);
const vi = Number.isInteger(args.video) ? args.video : 0;
const op = typeof args.op === 'string' ? args.op : 'status';
const to = Number(args.to);
const js = `(async () => {
const vs = [...document.querySelectorAll('video')];
const v = vs[${vi}];
if (v) {
${op === 'play' ? 'v.muted = true; await v.play().catch(() => {});' : ''}
${op === 'pause' ? 'v.pause();' : ''}
${op === 'seek' ? `v.currentTime = ${Number.isFinite(to) ? to : 0};` : ''}
${op === 'rate' ? `v.playbackRate = ${Number.isFinite(to) ? Math.min(Math.max(to, 0.1), 8) : 1};` : ''}
}
return { page: { url: location.href, title: document.title }, videos: vs.map((v) => {
const r = v.getBoundingClientRect();
return { playing: !v.paused && !v.ended, paused: v.paused, ended: v.ended,
currentTime: Math.round(v.currentTime * 100) / 100, duration: v.duration || 0,
muted: v.muted, volume: v.volume, rate: v.playbackRate, ready: v.readyState,
rect: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) },
src: (v.currentSrc || v.src || '').slice(0, 160) };
}) };
})()`;
const state = await evaluate(js);
const shotsN = Math.min(Number.isInteger(args.shots) ? args.shots : 0, 12);
const every = Math.min(Number.isInteger(args.every) ? args.every : 1000, 20000);
const shots = [];
for (let i = 0; i < shotsN; i++) {
const rect = state.videos[vi] && state.videos[vi].rect;
const file = path.join(os.homedir(), 'Documents', 'deepseek-harness', 'default-workspace', `edge-kit-video-${Date.now()}-${i}.png`);
const clip = rect && rect.w > 4 && rect.h > 4 ? { x: rect.x, y: rect.y, width: rect.w, height: rect.h } : undefined;
shots.push(await captureShot(file, clip));
if (i < shotsN - 1) await new Promise((r) => setTimeout(r, every));
}
return { ok: true, ...state, shots };
}
case 'scroll': {
await ensureActive(args);
const dir = args.direction === 'up' ? -1 : 1;
const px = Math.min(Number.isInteger(args.amount) ? args.amount : 600, 4000);
await evaluate(`window.scrollBy(0, ${dir * px}); 'ok'`);
return { ok: true, direction: dir > 0 ? 'down' : 'up', px };
}
case 'waitFor': {
await ensureActive(args);
const timeoutMs = Math.min(Number.isInteger(args.timeoutMs) ? args.timeoutMs : 10000, 30000);
const js = `(async () => {
${WALKER}
const needle = ${JSON.stringify(typeof args.text === 'string' ? args.text.toLowerCase() : '')};
const sel = ${JSON.stringify(typeof args.selector === 'string' ? args.selector : '')};
const start = Date.now();
const hasText = () => {
let found = (document.body ? document.body.innerText : '').toLowerCase().includes(needle);
if (found || !needle) return found;
const stack = [document];
while (stack.length) {
const root = stack.pop();
for (const el of root.querySelectorAll('*')) {
if (el.shadowRoot) { stack.push(el.shadowRoot); if (needle && el.shadowRoot.textContent.toLowerCase().includes(needle)) return true; }
}
}
return false;
};
while (Date.now() - start < ${timeoutMs}) {
if (sel && document.querySelector(sel)) return { found: true, how: 'selector', ms: Date.now() - start };
if (needle && hasText()) return { found: true, how: 'text', ms: Date.now() - start };
await new Promise((r) => setTimeout(r, 250));
}
return { found: false, ms: Date.now() - start };
})()`;
const r = await evaluate(js);
return { ok: true, ...r, ...await pageInfo() };
}
case 'eval': {
await ensureActive(args);
if (typeof args.script !== 'string') throw new Error('eval needs a script');
return { ok: true, result: await evaluate(`(async () => { ${args.script} })()`) };
}
case 'screenshot': {
await ensureActive(args);
const saveTo = typeof args.saveTo === 'string' && path.isAbsolute(args.saveTo) ? args.saveTo : undefined;
return { ok: true, ...await captureShot(saveTo) };
}
case 'wait': {
const ms = Math.min(Number.isInteger(args.ms) ? args.ms : 1000, 20000);
await new Promise((r) => setTimeout(r, ms));
return { ok: true, waited: ms };
}
case 'proxy': {
const raw = String(args.proxyChain || '').trim();
const entries = raw.split(/[\s,;]+/).map(parseProxy).filter(Boolean);
const op = ['auto', 'set', 'status', 'clear'].includes(args.op) ? args.op : (entries.length ? 'auto' : 'status');
if (op === 'clear') {
stopChain(); activeProxy = null;
const relaunched = await restartSession();
return { ok: true, cleared: true, relaunched, note: 'proxy removed; relaunch to route traffic direct' };
}
if (op === 'status') {
const view = activeProxyView();
const live = view ? await egressVia(view.mode === 'chain' ? chainHolder.hops : [parseProxy(activeProxy)]) : null;
return { ok: true, active: view && { ...view, exit: live }, settings: settingsSnapshot() };
}
if (!entries.length) return { ok: false, error: 'proxy: pass proxyChain "ip:port[,ip:port,...]" (auto tests candidates; set installs the list as the chain)' };
const tested = await Promise.all(entries.map(async (h) => ({ hop: h, ...(await probeCandidate(h)) })));
const working = tested.filter((t) => t.ok).sort((a, b) => a.ms - b.ms);
if (!working.length) return { ok: false, tested: entries.length, results: tested.map((t) => ({ proxy: chainLabel(t.hop), reason: t.reason, ms: t.ms })) };
const pick = working[0];
let hops;
if (op === 'set') hops = entries;
else {
hops = [pick.hop];
if (args.chainTo) { const second = parseProxy(args.chainTo); if (second) hops.push(second); }
}
let note = null;
let exit = null;
if (hops.length > 1) {
exit = await egressVia(hops);
if (!exit.ok) {
if (op === 'set') return { ok: false, error: `chain ${hops.map(chainLabel).join(' -> ')} rejected: ${exit.error || 'no echo'} (fastest single hop: ${chainLabel(pick.hop)}, exit ${pick.ip})` };
note = `chain ${hops.map(chainLabel).join(' -> ')} rejected (${exit.error || 'no echo'}) — applied the fastest single hop instead`;
hops = [pick.hop];
}
}
await ensureHolder(hops);
const relaunched = await restartSession();
const view = activeProxyView();
if (!exit) exit = await egressVia(hops);
return {
ok: true,
...(note ? { note } : {}),
active: { ...(view || {}), exit },
chosen: { proxy: chainLabel(pick.hop), ip: pick.ip, country: pick.country, ms: pick.ms },
relaunched,
tested: entries.length,
working: working.map((w) => ({ proxy: chainLabel(w.hop), ip: w.ip, country: w.country, ms: w.ms })).slice(0, 12),
};
}
case 'close': {
if (!session) return { ok: true, note: 'no active session' };
const { child, attached, ws } = session;
if (attached) {
// Firefox keeps its single BiDi session registered after a bare
// WebSocket close, so detach by ending that session first (the browser
// itself is borrowed and stays up).
try { if (session.engine === 'bidi' && session.bidiReady) await send('session.end', {}, null); } catch { /* best effort */ }
session = null;
try { ws.close(); } catch { /* already gone */ }
return { ok: true, detached: true, note: 'left the borrowed browser running (live mode)' };
}
await Promise.race([
send('Browser.close', {}, null).catch(() => {}),
new Promise((r) => setTimeout(r, 1500)),
]);
/* EDGE_KIT_NATIVE_CLOSE_FIX: clear the session only after Browser.close was sent; the
* upstream order cleared it first, so send() threw and close leaked the browser. */
session = null;
if (child && child.exitCode === null) child.kill();
try { ws.close(); } catch { /* already gone */ }
return { ok: true, closed: true };
}
default:
return { ok: false, error: `unknown action: ${action}` };
}
}
/* ── Native web providers (Exa-style): the harness web seam, pinned to this
* plugin by cordis.patch.yml, serves web_search / web_fetch through your
* real signed-in Edge — full JS rendering and a home fingerprint, so content
* that plain HTTP fetchers get wall-Blocked on still comes back clean. */
async function withPage(navigateTo, extract, signal) {
if (!session || session.ws.readyState !== 1) {
if (!initLock) initLock = (async () => {
try { await doLaunch({}); }
catch (e) {
// Seam calls have nobody to ask for a relaunch: if the signed-in
// profile is locked by the everyday Edge, degrade to the kit profile.
if (cfgVal('realProfile', true)) { await doLaunch({ profileDir: cfgVal('profileDir', '') || KIT_PROFILE }); return; }
throw e;
}
})().finally(() => { initLock = null; });
await initLock;
}
const { targetId } = await send('Target.createTarget', { url: 'about:blank' }, null);
const { sessionId: sid } = await send('Target.attachToTarget', { targetId, flatten: true }, null);
try {
await send('Page.enable', {}, sid);
await send('Page.navigate', { url: navigateTo }, sid);
const deadline = Date.now() + 20000;
while (Date.now() < deadline) {
if (signal && signal.aborted) throw new Error('web request aborted');
const r = await send('Runtime.evaluate', { expression: 'document.readyState', returnByValue: true }, sid);
if (r.result && r.result.value === 'complete') break;
await new Promise((res) => setTimeout(res, 400));
}
await new Promise((res) => setTimeout(res, 600)); // let hydration settle
const r = await send('Runtime.evaluate', { expression: extract, returnByValue: true, awaitPromise: true }, sid);
if (r.exceptionDetails) throw new Error(`page script error: ${r.exceptionDetails.text}`);
return r.result ? r.result.value : undefined;
} finally {
await send('Target.closeTarget', { targetId }, null).catch(() => {});
}
}
let initLock = null;
/* EDGE_KIT_NATIVE_PORTABILITY: keep the activation probe under the current user's
* home directory instead of a hardcoded developer path. */
const PROBE_FILE = path.join(os.homedir(), 'Documents', 'deepseek-harness', 'default-workspace', 'edge-kit-seam-probe.json');
let probed = false;
const FETCH_EXTRACT = `(async () => {
let status = 200;
try { const n = performance.getEntriesByType('navigation')[0]; if (n && typeof n.responseStatus === 'number') status = n.responseStatus; } catch {}
return { url: location.href, status, text: document.body ? document.body.innerText : '' };
})()`;
const SEARCH_EXTRACT = `(() => {
const clean = (s) => String(s || '').replace(/\\s+/g, ' ').trim();
const out = []; const seen = new Set();
const selfUrl = (u) => /^https?:\\/\\/(?:www\\.)?(?:bing|google|duckduckgo)\\./i.test(u);
// Organic result headlines come in both directions now: heading inside the
// link (Google: a > h3) AND link inside the heading (Bing: h2 > a). Match
// both — engine class names drift, the heading/link nesting does not.
for (const node of document.querySelectorAll('h2 a, h3 a, a h2, a h3')) {
if (out.length >= 20) break;
const link = node.matches('a') ? node : node.closest('a');
if (!link) continue;
let url = link.href;
if (/^\\/(url|link)\\?/.test(url)) { const m = url.match(/[?&](?:url|q)=([^&]+)/); if (m) { try { url = decodeURIComponent(m[1]); } catch {} } }
if (!/^https?:/i.test(url) || seen.has(url) || selfUrl(url)) continue;
const title = clean(link.innerText);
if (!title || title.length < 4) continue;
const box = link.closest('li,div.g,div.tF2Cxc,li.b_algo,div.b_title,div[class*=result]') || link.parentElement;
let snippet = box ? clean(box.innerText) : '';
if (snippet.startsWith(title)) snippet = snippet.slice(title.length).trim();
seen.add(url);
out.push({ url, title: title.slice(0, 200), ...(snippet ? { snippet: snippet.slice(0, 400) } : {}) });
}
return { sources: out, page: { url: location.href, title: clean(document.title) } };
})()`;
const edgeFetchProvider = {
id: 'edge-kit',
available: () => true,
async fetch(request, signal) {
const r = await withPage(request.url, FETCH_EXTRACT, signal) || {};
const cap = cfgVal('fetchTextCap', 20000);
let text = String(r.text || '');
const truncated = text.length > cap;
if (truncated) text = text.slice(0, cap);
return { url: r.url || request.url, statusCode: r.status || 200, body: { kind: 'text', content: text }, truncated };
},
};
const edgeSearchProvider = {
id: 'edge-kit',
available: () => true,
async search(request, signal) {
const n = Math.min(Math.max(request.maxResults ?? 10, 1), 20);
const q = encodeURIComponent(request.query);
const engine = cfgVal('searchEngine', 'google') === 'bing' ? 'bing' : 'google';
const build = (e) => e === 'bing'
? `https://www.bing.com/search?q=${q}&count=${Math.min(n * 2, 30)}`
: `https://www.google.com/search?q=${q}&num=${Math.min(n * 2, 20)}`;
const r = (await withPage(build(engine), SEARCH_EXTRACT, signal)) || {};
let sources = (r.sources || []).slice(0, n);
let page = r.page || {};
if (!sources.length) {
// Engine layouts and consent walls differ; an agent's search should
// survive either. Try the other engine once before reporting empty.
const alt = (await withPage(build(engine === 'bing' ? 'google' : 'bing'), SEARCH_EXTRACT, signal)) || {};
sources = (alt.sources || []).slice(0, n);
if (alt.page) page = alt.page;
}
return {
sources,
truncated: false,
...(sources.length || !page.url ? {} : { content: 'edge-kit search parsed no results; landed on ' + page.url + ' (title: ' + (page.title || 'none') + ')' }),
};
},
};
export function apply(ctx, config) {
cfg = config;
// One-time activation probe: run the seam's own fetch/search against this
// provider and record the outcome, proving selection + rendering end to end.
if (!probed) {
probed = true;
setTimeout(async () => {
const out = { at: new Date().toISOString() };
try {
const f = await ctx.web.fetch({ url: 'https://quotes.toscrape.com/js/' });
out.fetch = { url: f.url, statusCode: f.statusCode, kind: f.body.kind, length: f.body.content.length, truncated: f.truncated, sample: f.body.content.slice(0, 220) };
} catch (e) { out.fetchError = String((e && e.message) || e); }
try {
const s = await ctx.web.search({ query: 'deepseek harness', maxResults: 3 });
out.search = { count: s.sources.length, urls: s.sources.slice(0, 3).map((x) => x.url), content: s.content };
} catch (e) { out.searchError = String((e && e.message) || e); }
try { await fs.writeFile(PROBE_FILE, JSON.stringify(out, null, 2)); } catch { /* probe file optional */ }
}, 400);
}
ctx.effect(() => {
// The seam disposes provider registrations with the registering fiber,
// so they must live inside this effect, not at apply scope.
const offSearch = ctx.web.registerSearchProvider(edgeSearchProvider);
const offFetch = ctx.web.registerFetchProvider(edgeFetchProvider);
const dispose = ctx.tools.register({
name: 'edge_kit_browser',
description:
'Edge Kit Browser — browse like a human in Edge, Chrome, or Firefox. Flow: see (read the ' +
'page: text + numbered elements, shadow-DOM aware) then act: click {index|text|selector}, ' +
'clickAt {x,y}, drag {x,y,toX,toY}, type {into,text,submit?}, press {key,times}, scroll; ' +
'understand video: video {video?, op:status|play|pause|seek|rate, to?, shots?, every?} ' +
'returns playback state and PNG frames of the player; route traffic: proxy ' +
'{op:auto|set|status|clear, proxyChain:"ip:port[,ip:port]", chainTo?} verifies candidates with an ' +
'IP echo, moves the browser onto the fastest working proxy, and chains hops through a local ' +
'forwarder (exit IP reported); verify with waitFor {text|selector} ' +
'or screenshot; navigate with goto/back/forward/reload; organize with tabs/newTab/' +
'switchTab/closeTab. Session: launch (browser: edge|chrome|firefox; live-attaches to a ' +
'running debuggable browser first; realProfile:true keeps your logins; relaunch:true ' +
'restarts your browser debuggable), attach, status, wait {ms}, eval {script}, close ' +
'(detaches from borrowed browsers, never closes them).',
parameters: {
type: 'object',
properties: {
action: {
type: 'string',
enum: ['launch', 'attach', 'status', 'tabs', 'newTab', 'switchTab', 'closeTab', 'goto', 'back', 'forward', 'reload', 'see', 'click', 'clickAt', 'drag', 'video', 'type', 'press', 'scroll', 'waitFor', 'eval', 'screenshot', 'wait', 'proxy', 'close'],
description: 'What to do.',
},
url: { type: 'string', description: 'goto/newTab: address to open.' },
headless: { type: 'boolean', description: 'launch only: start hidden (default false = visible, like a person).' },
port: { type: 'integer', description: 'DevTools port (default comes from the Edge Kit settings page).' },
profileDir: { type: 'string', description: 'launch only: user-data-dir override.' },
realProfile: { type: 'boolean', description: 'launch only: use your everyday Edge profile (keeps all your logins). Default comes from the Edge Kit settings page.' },
relaunch: { type: 'boolean', description: 'launch only: restart a running profile-owning Edge so it becomes debuggable.' },
executablePath: { type: 'string', description: 'launch only: msedge.exe path override.' },
index: { type: 'integer', description: 'click: element number from the most recent see. switchTab/closeTab: tab number from tabs.' },
targetId: { type: 'string', description: 'switchTab/closeTab: exact target id.' },
text: { type: 'string', description: 'click: visible text to click. type: text to enter. waitFor: text to wait for.' },
into: { type: 'string', description: 'type: human label of the field (label/placeholder/aria-label).' },
submit: { type: 'boolean', description: 'type: press Enter after typing.' },
selector: { type: 'string', description: 'click: CSS selector (light DOM). waitFor: selector to wait for.' },
script: { type: 'string', description: 'eval: JS statements (await allowed).' },
key: { type: 'string', description: 'press: key name (default Enter).' },
direction: { type: 'string', enum: ['up', 'down'], description: 'scroll direction.' },
amount: { type: 'integer', description: 'scroll pixels (default 600).' },
ms: { type: 'integer', description: 'wait: milliseconds.' },
timeoutMs: { type: 'integer', description: 'waitFor: max milliseconds (default 10000).' },
maxText: { type: 'integer', description: 'see: page-text cap (default 2200).' },
saveTo: { type: 'string', description: 'screenshot: absolute PNG path to write.' },
browser: { type: 'string', enum: ['edge', 'chrome', 'firefox'], description: 'launch: which browser to start (default comes from the settings page).' },
x: { type: 'integer', description: 'clickAt/drag: x coordinate.' },
y: { type: 'integer', description: 'clickAt/drag: y coordinate.' },
toX: { type: 'integer', description: 'drag: destination x.' },
toY: { type: 'integer', description: 'drag: destination y.' },
times: { type: 'integer', description: 'press: repeat the key this many times (games).' },
video: { type: 'integer', description: 'video: which video element on the page (0 = first).' },
op: { type: 'string', enum: ['status', 'play', 'pause', 'seek', 'rate', 'auto', 'set', 'clear'], description: 'video: what to do. proxy: auto (test list, use fastest working), set (use list as-is), status, clear.' },
to: { type: 'number', description: 'video seek: seconds; video rate: playback speed.' },
shots: { type: 'integer', description: 'video: also capture this many PNG frames (max 12).' },
every: { type: 'integer', description: 'video: milliseconds between frames (default 1000).' },
proxyChain: { type: 'string', description: 'proxy: comma-separated ip:port list — candidates for op "auto", or the exact chain for op "set" (2+ hops chain through the in-kit local forwarder).' },
chainTo: { type: 'string', description: 'proxy auto: chain this extra ip:port hop behind the winning proxy.' },
},
additionalProperties: false,
},
output: {
schema: { type: 'object' },
render: (args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
},
execute: async (args) => run(args),
});
return () => {
// Release the browser this plugin owns — or only the BiDi session when the
// browser is borrowed. Killing the spawn handle alone is not enough for
// Firefox (it is only the Windows launcher), so the browser could outlive
// the host with its single BiDi session still registered.
const ending = session;
try {
if (ending && ending.attached && ending.engine === 'bidi' && ending.bidiReady) {
ending.ws.send(JSON.stringify({ id: nextId++, method: 'session.end', params: {} }));
} else if (ending && !ending.attached && ending.ws.readyState === 1) {
ending.ws.send(JSON.stringify({ id: nextId++, method: ending.engine === 'bidi' ? 'browser.close' : 'Browser.close', params: {} }));
}
} catch { /* already gone */ }
try { ending?.child?.kill(); } catch { /* already gone */ }
try { ending?.ws?.close(); } catch { /* already gone */ }
session = null;
lastElements = [];
cfg = null;
offSearch();
offFetch();
dispose();
stopChain();
};
});
}