v3.6.1: no-v2ray launch pinning (strip proxy env, explicit --no-proxy-server / FF direct prefs), cross-platform browser discovery (Win/Linux/macOS incl. snap chromium), setup.mjs deploy self-check, README deploy docs

This commit is contained in:
2026-11-08 20:52:45 +03:30
parent 40f6737183
commit 19b0246828
4 changed files with 168 additions and 11 deletions
+10 -1
View File
@@ -14,6 +14,12 @@ The kit talks to the browser the way a person does: it *sees* the page (visible
## Install ## Install
Run the deploy self-check first — it finds your browsers, checks Node, ports, profile dirs and direct egress, then prints the exact integration steps (Windows, Linux and macOS):
```bash
node setup.mjs # exit code 0 = ready to integrate
```
Copy this package into your harness profile (or `pnpm install` it as a workspace link), then add to your composition: Copy this package into your harness profile (or `pnpm install` it as a workspace link), then add to your composition:
```yaml ```yaml
@@ -45,9 +51,11 @@ Firefox (158+) exposes WebDriver BiDi on its debug port rather than CDP; the ada
Per-browser profiles: the user's real profile by default (`realProfile`), or isolated kit profiles under `~/.dsh/browser-profiles/edge-kit[-chrome|-firefox]`. If your everyday browser owns the profile, pass `relaunch: true` to restart it debuggable (logins survive) or set `profileDir`. Per-browser profiles: the user's real profile by default (`realProfile`), or isolated kit profiles under `~/.dsh/browser-profiles/edge-kit[-chrome|-firefox]`. If your everyday browser owns the profile, pass `relaunch: true` to restart it debuggable (logins survive) or set `profileDir`.
Browser discovery is cross-platform — Windows, Linux (apt **and** snap paths, including `chromium`) and macOS, for all three browsers; pass `executablePath` for anything exotic.
## Actions ## Actions
`launch` · `attach` · `status` · `tabs` · `newTab` · `switchTab` · `closeTab` · `goto` · `back` · `forward` · `reload` · `see` · `click` · `clickAt` · `drag` · `video` · `type` · `press` · `scroll` · `waitFor` · `eval` · `screenshot` · `wait` · `close` `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`
## Proxy support ## Proxy support
@@ -57,6 +65,7 @@ Per-browser profiles: the user's real profile by default (`realProfile`), or iso
- **set** — installs a list verbatim. One hop is handed to the browser directly (`--proxy-server`); two or more are **chained** through an in-kit local CONNECT forwarder (browser → 127.0.0.1 → hop1 → hop2 → … → origin), verified end-to-end before the switch — a rejected chain falls back to the fastest single hop (or errors, in `set`). - **set** — installs a list verbatim. One hop is handed to the browser directly (`--proxy-server`); two or more are **chained** through an in-kit local CONNECT forwarder (browser → 127.0.0.1 → hop1 → hop2 → … → origin), verified end-to-end before the switch — a rejected chain falls back to the fastest single hop (or errors, in `set`).
- **status** — live re-probe of the current route; **clear** — direct traffic again. `chainTo` adds one chained hop behind the auto-pick. - **status** — live re-probe of the current route; **clear** — direct traffic again. `chainTo` adds one chained hop behind the auto-pick.
- The `proxyChain` setting preloads a chain into every launch; the native web seam (`web_fetch` / `web_search`) rides the same route. - The `proxyChain` setting preloads a chain into every launch; the native web seam (`web_fetch` / `web_search`) rides the same route.
- **Fully built in** — no system/v2ray proxy anywhere in the path: probes use raw sockets, and launched browsers get explicit proxy state (`--proxy-server` when routing; `--no-proxy-server` / `network.proxy.type:0` when direct, with `HTTP(S)_PROXY`/`ALL_PROXY` stripped from the launch environment). A local v2ray can never silently capture the browser.
A proxy counts as *working* only when an echo comes back through it — no blind trust in proxy-list sites. A proxy counts as *working* only when an echo comes back through it — no blind trust in proxy-list sites.
+43 -9
View File
@@ -89,31 +89,52 @@ const settingsSnapshot = () => ({
const DEFAULT_PORT = 9444; const DEFAULT_PORT = 9444;
const KIT_PROFILE = path.join(os.homedir(), '.dsh', 'browser-profiles', 'edge-kit'); 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 const REAL_PROFILE = process.env.LOCALAPPDATA
? path.join(process.env.LOCALAPPDATA, 'Microsoft', 'Edge', 'User Data') ? 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; : null;
const CHROME_REAL_PROFILE = process.env.LOCALAPPDATA const CHROME_REAL_PROFILE = process.env.LOCALAPPDATA
? path.join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'User Data') ? 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; : null;
const FF_PROFILES_ROOT = process.env.APPDATA const FF_PROFILES_ROOT = process.env.APPDATA
? path.join(process.env.APPDATA, 'Mozilla', 'Firefox', 'Profiles') ? path.join(process.env.APPDATA, 'Mozilla', 'Firefox')
: process.platform === 'linux' || process.platform === 'darwin' ? path.join(os.homedir(), '.mozilla', 'firefox')
: null; : null;
const IS_WIN = process.platform === 'win32';
const BROWSER_CANDIDATES = { const BROWSER_CANDIDATES = {
edge: [ edge: IS_WIN ? [
'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe', 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
'C:\\Program Files\\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: [ chrome: IS_WIN ? [
'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
process.env.LOCALAPPDATA + '\\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: [ firefox: IS_WIN ? [
'C:\\Program Files\\Mozilla Firefox\\firefox.exe', 'C:\\Program Files\\Mozilla Firefox\\firefox.exe',
'C:\\Program Files (x86)\\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' : /chrome/i.test(exe) ? 'chrome' : 'edge'; 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. // Firefox's real profile is whichever profiles.ini marks Default=1.
async function ffDefaultProfile() { async function ffDefaultProfile() {
@@ -406,12 +427,17 @@ async function doLaunch(args) {
await fs.mkdir(profileDir, { recursive: true }); await fs.mkdir(profileDir, { recursive: true });
const headless = args.headless ?? cfgVal('headless', false); const headless = args.headless ?? cfgVal('headless', false);
const proxyFlag = await launchProxyFlag(args); 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' ? [ const child = spawn(executable, kind === 'firefox' ? [
`-remote-debugging-port=${port}`, `-remote-debugging-port=${port}`,
'-profile', profileDir, '-profile', profileDir,
'-no-remote', '-no-remote',
...(headless ? ['-headless'] : []), ...(headless ? ['-headless'] : []),
...(proxyFlag ? ['-proxy-server', proxyFlag] : []), ...(proxyFlag ? ['-proxy-server', proxyFlag] : ['-preferences', '{"network.proxy.type":0}']),
'about:blank', 'about:blank',
] : [ ] : [
`--remote-debugging-port=${port}`, `--remote-debugging-port=${port}`,
@@ -424,9 +450,9 @@ async function doLaunch(args) {
'--disable-backgrounding-occluded-windows', '--disable-backgrounding-occluded-windows',
'--disable-renderer-backgrounding', '--disable-renderer-backgrounding',
...(headless ? ['--headless=new'] : []), ...(headless ? ['--headless=new'] : []),
...(proxyFlag ? [`--proxy-server=${proxyFlag}`] : []), ...(proxyFlag ? [`--proxy-server=${proxyFlag}`] : ['--no-proxy-server']),
'about:blank', 'about:blank',
], { stdio: 'ignore', detached: false }); ], { stdio: 'ignore', detached: false, env: childEnv });
if (!(await waitForPort(port, 25000))) { if (!(await waitForPort(port, 25000))) {
child.kill(); 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.'); 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.');
@@ -573,7 +599,15 @@ function startChainServer(hops) {
const i = buf.indexOf('\r\n\r\n'); const i = buf.indexOf('\r\n\r\n');
if (i < 0) { if (buf.length > 65536) client.destroy(); return; } if (i < 0) { if (buf.length > 65536) client.destroy(); return; }
client.removeListener('data', onData); client.removeListener('data', onData);
handle(client, buf.slice(0, i), buf.slice(i + 4)); // 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); client.on('data', onData);
}); });
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "@local/edge-kit-easy", "name": "@local/edge-kit-easy",
"version": "3.6.0", "version": "3.6.1",
"private": true, "private": true,
"type": "module", "type": "module",
"description": "Edge Kit Browser — human-style browsing for agents in Edge, Chrome, or Firefox: see, click, type, video understanding, gameplay; live-attach-first over CDP/BiDi with a native settings page and the native web seam", "description": "Edge Kit Browser — human-style browsing for agents in Edge, Chrome, or Firefox: see, click, type, video understanding, gameplay; live-attach-first over CDP/BiDi with a native settings page and the native web seam",
+114
View File
@@ -0,0 +1,114 @@
#!/usr/bin/env node
/* Edge Kit deploy check — run me first: node setup.mjs
* Auto-detects the environment (Windows / Linux / macOS) for all supported
* browsers, verifies everything the kit needs, and prints exact next steps.
* The kit's proxy is fully built in: nothing here — and nothing the kit does —
* ever depends on a system/v2ray proxy. Node fetch ignores proxy env vars, so
* the egress check below is always direct.
* Exit code 0 = ready. */
import fs from 'node:fs/promises';
import os from 'node:os';
import net from 'node:net';
import path from 'node:path';
const P = process.platform;
const HOME = os.homedir();
let failures = 0;
const ok = (s) => console.log(' [ok] ' + s);
const warn = (s) => console.log(' [warn] ' + s);
const fail = (s) => { console.log(' [FAIL] ' + s); failures++; };
console.log('Edge Kit environment check — ' + P + ' ' + os.arch() + ', node ' + process.version + '\n');
/* 1. Node version (kit uses fetch/AbortSignal/WS built-ins) */
const maj = Number(process.versions.node.split('.')[0]);
if (maj >= 18) ok(`node ${process.version}`);
else fail(`node ${process.version} — Edge Kit needs >= 18 (fetch/AbortSignal)`);
/* 2. Browsers (same discovery table as the kit itself) */
const W = P === 'win32';
const CAND = {
edge: W
? ['C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe', 'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe']
: P === '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: W
? ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe']
: P === '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: W
? ['C:\\Program Files\\Mozilla Firefox\\firefox.exe', 'C:\\Program Files (x86)\\Mozilla Firefox\\firefox.exe']
: P === 'darwin'
? ['/Applications/Firefox.app/Contents/MacOS/firefox']
: ['/usr/lib/firefox/firefox', '/usr/bin/firefox', '/snap/bin/firefox'],
};
const found = {};
for (const [kind, list] of Object.entries(CAND)) {
for (const p of list) {
try { await fs.access(p); (found[kind] ||= []).push(p); break; } catch { /* next */ }
}
}
for (const kind of ['edge', 'chrome', 'firefox']) {
if (found[kind]) ok(`${kind}: ${found[kind][0]}`);
else warn(`${kind}: not found — install it (or pass executablePath per call)`);
}
if (!Object.keys(found).length) fail('no supported browser found — the kit needs at least one of edge/chrome/firefox');
/* 3. Kit profile dir writable (fresh launch profiles live here) */
const kitDir = path.join(HOME, '.dsh', 'browser-profiles', 'edge-kit');
try {
await fs.mkdir(kitDir, { recursive: true });
await fs.writeFile(path.join(kitDir, '.setup-probe'), 'x');
await fs.rm(path.join(kitDir, '.setup-probe'));
ok('profile dir writable: ' + kitDir);
} catch (e) { fail(`cannot write ${kitDir}: ${e.message}`); }
/* 4. DevTools ports */
for (const port of [9444, 9445, 9446]) {
const free = await new Promise((r) => {
const s = net.createServer();
s.once('error', () => r(false));
s.listen(port, '127.0.0.1', () => s.close(() => r(true)));
});
if (free) ok(`debug port ${port} free`);
else warn(`debug port ${port} busy — a browser already holds it; the kit will attach to it (relaunch:true takes over)`);
}
/* 5. Direct egress — proves there is an internet path WITHOUT any system/v2ray
* proxy (node fetch never reads HTTP_PROXY). Geo-restricted hosts (Iran)
* often have no open HTTP echo without VPN but can reach proxies directly
* over raw TCP — which is all the kit ever needs — so fall back to that. */
let egress = null;
for (const url of ['http://checkip.amazonaws.com/', 'https://api.ipify.org']) {
try { const r = await fetch(url, { signal: AbortSignal.timeout(7000) }); egress = (await r.text()).trim().split(/\s/)[0]; break; } catch { /* next echo */ }
}
if (egress) ok(`direct egress: ${egress} (no system proxy involved)`);
else {
let tcpOk = false;
for (const [host, port] of [['34.43.46.91', 80], ['1.1.1.1', 443], ['8.8.8.8', 53]]) {
tcpOk = await new Promise((r) => {
const s = net.connect({ host, port });
const t = setTimeout(() => { s.destroy(); r(false); }, 6000);
s.once('connect', () => { clearTimeout(t); s.destroy(); r(true); });
s.once('error', () => { clearTimeout(t); r(false); });
});
if (tcpOk) { warn(`no open HTTP echo (geo-blocked without VPN?) — raw TCP to ${host}:${port} works, which is all the kit needs: it routes through verified proxies`); break; }
}
if (!tcpOk) fail('no usable internet path at all (no HTTP echo, no raw TCP) — fix the network before installing');
}
const sysProxy = process.env.HTTP_PROXY || process.env.http_proxy || process.env.HTTPS_PROXY || process.env.https_proxy;
if (sysProxy) warn(`shell proxy var present (${sysProxy}) — ignored by design: the kit pins browser proxy state itself`);
/* 6. Integration summary */
console.log(`
${failures ? `${failures} blocking issue(s) above — fix and re-run.` : 'Ready to integrate.'}
1. Install the kit into your agent host: point its plugin manager at this folder
(e.g. {action:"install_bundle", target:"${process.cwd()}"}), or add to the host's
composition: "plugin: { kit: { path: '${process.cwd()}' } }".
2. The web seam (web_fetch/web_search) is pinned to the kit via cordis.patch.yml —
the host applies it automatically; the kit lazily launches a browser on first use.
3. First call: {action:"status"}; browse: {action:"goto", url:"https://…"}, {action:"see"}.
4. Optional verified routing: {action:"proxy", op:"auto", proxyChain:"ip:port,…"}.`);
process.exitCode = failures ? 1 : 0;