turno-browser 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +98 -0
- package/README.md +32 -3
- package/dist/act-model.d.ts +85 -0
- package/dist/act-model.js +116 -0
- package/dist/act.d.ts +37 -0
- package/dist/act.js +599 -0
- package/dist/api.d.ts +29 -2
- package/dist/api.js +29 -2
- package/dist/argv.d.ts +16 -2
- package/dist/argv.js +100 -3
- package/dist/batch.d.ts +5 -0
- package/dist/batch.js +3 -3
- package/dist/bin/mcp.js +58 -1
- package/dist/captcha.d.ts +77 -0
- package/dist/captcha.js +333 -0
- package/dist/cdp-relay.d.ts +20 -0
- package/dist/cdp-relay.js +101 -0
- package/dist/chrome-features.d.ts +23 -0
- package/dist/chrome-features.js +44 -0
- package/dist/diagnose.d.ts +7 -0
- package/dist/diagnose.js +61 -6
- package/dist/doctor.d.ts +37 -3
- package/dist/doctor.js +230 -5
- package/dist/engine-attach.d.ts +27 -0
- package/dist/engine-attach.js +165 -0
- package/dist/engine-camoufox.d.ts +32 -0
- package/dist/engine-camoufox.js +270 -0
- package/dist/engine-lightpanda.d.ts +72 -0
- package/dist/engine-lightpanda.js +292 -0
- package/dist/engine.d.ts +63 -11
- package/dist/engine.js +104 -28
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +42 -7
- package/dist/governor.js +82 -32
- package/dist/host.d.ts +17 -2
- package/dist/host.js +618 -41
- package/dist/human-input.d.ts +84 -0
- package/dist/human-input.js +443 -0
- package/dist/humanize.d.ts +123 -0
- package/dist/humanize.js +241 -0
- package/dist/identities.js +2 -0
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/index.d.ts +8 -3
- package/dist/index.js +5 -1
- package/dist/lifecycle.d.ts +9 -1
- package/dist/lifecycle.js +9 -1
- package/dist/live-client.d.ts +22 -0
- package/dist/live-client.js +93 -0
- package/dist/live-page.d.ts +11 -0
- package/dist/live-page.js +143 -0
- package/dist/live-server.d.ts +173 -0
- package/dist/live-server.js +640 -0
- package/dist/live.d.ts +120 -0
- package/dist/live.js +203 -0
- package/dist/login-tool.d.ts +13 -0
- package/dist/login-tool.js +5 -1
- package/dist/login.d.ts +4 -1
- package/dist/login.js +11 -2
- package/dist/network-chrome.d.ts +74 -0
- package/dist/network-chrome.js +178 -0
- package/dist/network.d.ts +125 -0
- package/dist/network.js +263 -0
- package/dist/opt-in-settings.d.ts +69 -0
- package/dist/opt-in-settings.js +151 -0
- package/dist/recorder.d.ts +88 -0
- package/dist/recorder.js +538 -0
- package/dist/recordings.d.ts +116 -0
- package/dist/recordings.js +474 -0
- package/dist/redact.d.ts +7 -0
- package/dist/redact.js +18 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +382 -0
- package/dist/reputation.d.ts +24 -2
- package/dist/reputation.js +63 -17
- package/dist/session-export.js +1 -1
- package/dist/session.d.ts +10 -2
- package/dist/session.js +10 -2
- package/dist/settings.d.ts +104 -2
- package/dist/settings.js +204 -6
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -2
- package/dist/snippet.js +10 -4
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +38 -0
- package/dist/tools.js +20 -1
- package/dist/tuning.d.ts +14 -0
- package/dist/tuning.js +9 -0
- package/dist/upstream.d.ts +11 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
import { execFileSync } from "node:child_process";
|
|
2
|
+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { createRequire } from "node:module";
|
|
5
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
6
|
+
import { findOnPath, browserPaths as paths } from "turno-core/paths";
|
|
7
|
+
import { IdleTimer, idleMs } from "./idle-timer.js";
|
|
8
|
+
import { identityStateDir } from "./ids.js";
|
|
9
|
+
import { FIREFOX_PROXY_PREFS, resolveProxy } from "./network.js";
|
|
10
|
+
import { acquireRuntimeLock } from "./runtime-lock.js";
|
|
11
|
+
import { acceptLanguages, chromeEnv, readIdentitySettings, systemTimezone } from "./settings.js";
|
|
12
|
+
import { upstream } from "./upstream.js";
|
|
13
|
+
/**
|
|
14
|
+
* The `camoufox` engine: Camoufox, a Firefox build with its own fingerprint handling, instead
|
|
15
|
+
* of Chrome. Opt-in only (identity.json `"engine": "camoufox"`, or `--engine camoufox`), off by
|
|
16
|
+
* default, and not recommended for the user's own accounts: a Firefox with a changed fingerprint
|
|
17
|
+
* is something sites look for, and the identity's Chrome profile and sign-ins do not carry over.
|
|
18
|
+
*
|
|
19
|
+
* turno never downloads it. Two things must be installed:
|
|
20
|
+
*
|
|
21
|
+
* - Camoufox itself: `TURNO_CAMOUFOX_PATH` (the executable, an absolute path), else the newest
|
|
22
|
+
* build Camoufox's own installer (`pip install camoufox`, then `camoufox fetch`) put in its
|
|
23
|
+
* cache folder.
|
|
24
|
+
* - Stock Playwright (`playwright-core`) of the same minor version as patchright-core.
|
|
25
|
+
* patchright-core drives Chromium only: with a Firefox build, evaluate fails and every action
|
|
26
|
+
* times out (measured with Playwright's Firefox 157). Firefox speaks Playwright's Juggler
|
|
27
|
+
* protocol, which stock Playwright drives. It is found next to turno-browser (`npm install -g
|
|
28
|
+
* playwright-core@<version>`) or at `TURNO_PLAYWRIGHT_CORE` (its package folder).
|
|
29
|
+
*
|
|
30
|
+
* The context it launches is handed to the same upstream tool backend as Chrome's, so the
|
|
31
|
+
* stock tools behave the same; the ones in `NOT_IN_CAMOUFOX` are refused before they run.
|
|
32
|
+
*
|
|
33
|
+
* For an identity, Camoufox keeps its own Firefox profile in
|
|
34
|
+
* `<state>/browser/identities/<id>/camoufox-profile`: it never opens the identity's Chrome
|
|
35
|
+
* profile, so a sign-in made in Chrome is not there. The identity's runtime lock is held while
|
|
36
|
+
* it runs, so a Chrome and a Camoufox never drive one identity at once. turno passes Camoufox no
|
|
37
|
+
* generated fingerprint: it presents the values its build reports for this computer.
|
|
38
|
+
*/
|
|
39
|
+
/** Tools that do not run on Camoufox, with the reason. */
|
|
40
|
+
const NOT_IN_CAMOUFOX = {
|
|
41
|
+
browser_run_code_unsafe: "it runs Playwright code against the patchright-core API, and Camoufox runs on stock Playwright",
|
|
42
|
+
browser_solve_captcha: "it sets the token from Patchright's isolated script world and calls the widget's callback in the page's own, and Camoufox runs on stock Playwright",
|
|
43
|
+
};
|
|
44
|
+
/** Why the Camoufox engine refuses this tool, or undefined when it runs it. */
|
|
45
|
+
export function camoufoxRefusal(tool) {
|
|
46
|
+
const why = NOT_IN_CAMOUFOX[tool];
|
|
47
|
+
if (!why)
|
|
48
|
+
return undefined;
|
|
49
|
+
return `${tool} is not available with the Camoufox engine: ${why}. Use the Chrome engine for it (\`turno browser set <id> --engine chrome\`).`;
|
|
50
|
+
}
|
|
51
|
+
/** How to install Camoufox, for errors and `turno browser doctor`. */
|
|
52
|
+
export function camoufoxInstallHint(platform = process.platform) {
|
|
53
|
+
if (platform === "win32")
|
|
54
|
+
return "pip install -U camoufox, then camoufox fetch (turno-browser does not run on Windows; use WSL)";
|
|
55
|
+
return "pip install -U camoufox && camoufox fetch (then set TURNO_CAMOUFOX_PATH if turno does not find it)";
|
|
56
|
+
}
|
|
57
|
+
/** Where Camoufox's own installer keeps its builds (platformdirs' user cache folder). */
|
|
58
|
+
export function camoufoxCacheDir(env, platform = process.platform) {
|
|
59
|
+
const home = paths(env).home;
|
|
60
|
+
if (platform === "darwin")
|
|
61
|
+
return join(home, "Library", "Caches", "camoufox");
|
|
62
|
+
return join(env.XDG_CACHE_HOME || join(home, ".cache"), "camoufox");
|
|
63
|
+
}
|
|
64
|
+
/** The executable inside one Camoufox build folder, if it has one. */
|
|
65
|
+
function executableIn(dir, platform) {
|
|
66
|
+
const file = platform === "darwin" ? join(dir, "Camoufox.app", "Contents", "MacOS", "camoufox") : join(dir, "camoufox-bin");
|
|
67
|
+
return existsSync(file) && statSync(file).isFile() ? file : undefined;
|
|
68
|
+
}
|
|
69
|
+
/** The newest Camoufox build under its cache folder, searched a few levels deep. */
|
|
70
|
+
function newestBuild(root, platform) {
|
|
71
|
+
const found = [];
|
|
72
|
+
const walk = (dir, depth) => {
|
|
73
|
+
const exe = executableIn(dir, platform);
|
|
74
|
+
if (exe) {
|
|
75
|
+
found.push({ file: exe, mtime: statSync(exe).mtimeMs });
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
if (depth === 0)
|
|
79
|
+
return;
|
|
80
|
+
let entries;
|
|
81
|
+
try {
|
|
82
|
+
entries = readdirSync(dir);
|
|
83
|
+
}
|
|
84
|
+
catch {
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
for (const e of entries) {
|
|
88
|
+
if (e.startsWith(".") || e.endsWith(".app"))
|
|
89
|
+
continue;
|
|
90
|
+
const sub = join(dir, e);
|
|
91
|
+
try {
|
|
92
|
+
if (statSync(sub).isDirectory())
|
|
93
|
+
walk(sub, depth - 1);
|
|
94
|
+
}
|
|
95
|
+
catch {
|
|
96
|
+
/* gone */
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
};
|
|
100
|
+
walk(root, 4);
|
|
101
|
+
return found.sort((a, b) => b.mtime - a.mtime)[0]?.file;
|
|
102
|
+
}
|
|
103
|
+
/** The Camoufox turno would run: `TURNO_CAMOUFOX_PATH`, else the newest build in Camoufox's cache folder. */
|
|
104
|
+
export function findCamoufox(env = process.env, platform = process.platform) {
|
|
105
|
+
const configured = env.TURNO_CAMOUFOX_PATH?.trim();
|
|
106
|
+
const path = configured
|
|
107
|
+
? isAbsolute(configured) && findOnPath(configured, env) && statSync(configured).isFile()
|
|
108
|
+
? configured
|
|
109
|
+
: undefined
|
|
110
|
+
: newestBuild(camoufoxCacheDir(env, platform), platform);
|
|
111
|
+
if (!path)
|
|
112
|
+
return undefined;
|
|
113
|
+
try {
|
|
114
|
+
const out = execFileSync(path, ["--version"], {
|
|
115
|
+
encoding: "utf8",
|
|
116
|
+
timeout: 5000,
|
|
117
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
118
|
+
env: { ...env, MOZ_HEADLESS: "1" },
|
|
119
|
+
}).trim();
|
|
120
|
+
return out ? { path, version: out.split("\n")[0].trim() } : { path };
|
|
121
|
+
}
|
|
122
|
+
catch {
|
|
123
|
+
return { path };
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
/** The error when Camoufox is missing, with the install command. */
|
|
127
|
+
function camoufoxMissing(env) {
|
|
128
|
+
const configured = env.TURNO_CAMOUFOX_PATH?.trim();
|
|
129
|
+
const where = configured
|
|
130
|
+
? `TURNO_CAMOUFOX_PATH (${configured}) is not an executable file with an absolute path`
|
|
131
|
+
: `no Camoufox build is in ${camoufoxCacheDir(env)}`;
|
|
132
|
+
return new Error(`the camoufox engine needs Camoufox, and ${where}. Install it: ${camoufoxInstallHint()}. turno never downloads it for you; \`turno browser doctor\` checks it.`);
|
|
133
|
+
}
|
|
134
|
+
/** The minor version of Playwright that patchright-core is built on, like "1.64". */
|
|
135
|
+
export function playwrightMinor() {
|
|
136
|
+
return upstream().version.split(".").slice(0, 2).join(".");
|
|
137
|
+
}
|
|
138
|
+
const require = createRequire(import.meta.url);
|
|
139
|
+
/**
|
|
140
|
+
* The stock `playwright-core` this engine would load: `TURNO_PLAYWRIGHT_CORE` (its package
|
|
141
|
+
* folder), else the one Node finds from turno-browser. Undefined when there is none; `ok` is
|
|
142
|
+
* false when its minor version is not patchright-core's.
|
|
143
|
+
*/
|
|
144
|
+
export function findPlaywrightCore(env = process.env) {
|
|
145
|
+
let manifest;
|
|
146
|
+
const configured = env.TURNO_PLAYWRIGHT_CORE?.trim();
|
|
147
|
+
if (configured)
|
|
148
|
+
manifest = isAbsolute(configured) ? join(configured, "package.json") : undefined;
|
|
149
|
+
else {
|
|
150
|
+
try {
|
|
151
|
+
manifest = require.resolve("playwright-core/package.json");
|
|
152
|
+
}
|
|
153
|
+
catch {
|
|
154
|
+
manifest = undefined;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
if (!manifest || !existsSync(manifest))
|
|
158
|
+
return undefined;
|
|
159
|
+
try {
|
|
160
|
+
const pkg = JSON.parse(readFileSync(manifest, "utf8"));
|
|
161
|
+
if (pkg.name !== "playwright-core" || typeof pkg.version !== "string")
|
|
162
|
+
return undefined;
|
|
163
|
+
const minor = pkg.version.split(".").slice(0, 2).join(".");
|
|
164
|
+
return { dir: dirname(manifest), version: pkg.version, ok: minor === playwrightMinor() };
|
|
165
|
+
}
|
|
166
|
+
catch {
|
|
167
|
+
return undefined;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
/** How to install the stock Playwright this engine needs. */
|
|
171
|
+
export function playwrightCoreHint() {
|
|
172
|
+
return `npm install -g playwright-core@${playwrightMinor()} (next to turno-browser), or set TURNO_PLAYWRIGHT_CORE to its folder`;
|
|
173
|
+
}
|
|
174
|
+
function loadFirefox(env) {
|
|
175
|
+
const found = findPlaywrightCore(env);
|
|
176
|
+
if (!found)
|
|
177
|
+
throw new Error(`the camoufox engine needs stock Playwright (playwright-core ${playwrightMinor()}): patchright-core drives Chromium only. Install it: ${playwrightCoreHint()}`);
|
|
178
|
+
if (!found.ok)
|
|
179
|
+
throw new Error(`the camoufox engine needs playwright-core ${playwrightMinor()}.x, the version patchright-core is built on, and found ${found.version} at ${found.dir}. Install it: ${playwrightCoreHint()}`);
|
|
180
|
+
return require(found.dir).firefox;
|
|
181
|
+
}
|
|
182
|
+
/** Where an identity's Camoufox keeps its Firefox profile. */
|
|
183
|
+
export function camoufoxProfileDir(id, env) {
|
|
184
|
+
return join(identityStateDir(id, env), "camoufox-profile");
|
|
185
|
+
}
|
|
186
|
+
export function createCamoufoxEngine() {
|
|
187
|
+
return {
|
|
188
|
+
id: "camoufox",
|
|
189
|
+
refuse: camoufoxRefusal,
|
|
190
|
+
async launch({ config, identity, secret }) {
|
|
191
|
+
const env = identity?.env ?? process.env;
|
|
192
|
+
const found = findCamoufox(env);
|
|
193
|
+
if (!found)
|
|
194
|
+
throw camoufoxMissing(env);
|
|
195
|
+
const firefox = loadFirefox(env);
|
|
196
|
+
const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
|
|
197
|
+
const proxy = settings?.proxy ? await resolveProxy(settings.proxy, env, secret ?? (() => { })) : undefined;
|
|
198
|
+
const languages = settings ? acceptLanguages(settings) : undefined;
|
|
199
|
+
const tz = settings?.timezone && settings.timezone !== systemTimezone() ? settings.timezone : undefined;
|
|
200
|
+
const held = identity ? acquireRuntimeLock(identity.id, identity.env, { holder: "mcp" }) : undefined;
|
|
201
|
+
// Without an identity, a throwaway profile removed when the browser closes.
|
|
202
|
+
const temporary = identity ? undefined : mkdtempSync(join(env.TMPDIR || tmpdir(), "turno-camoufox-"));
|
|
203
|
+
// Firefox may still be writing to it as the context closes: retry, and never throw from
|
|
204
|
+
// a close handler (that would end the server).
|
|
205
|
+
const removeTemporary = () => {
|
|
206
|
+
if (!temporary)
|
|
207
|
+
return;
|
|
208
|
+
try {
|
|
209
|
+
rmSync(temporary, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
|
|
210
|
+
}
|
|
211
|
+
catch {
|
|
212
|
+
/* left in the temp folder; the OS clears it */
|
|
213
|
+
}
|
|
214
|
+
};
|
|
215
|
+
let context;
|
|
216
|
+
try {
|
|
217
|
+
const dir = identity ? camoufoxProfileDir(identity.id, identity.env) : temporary;
|
|
218
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
219
|
+
const prefs = {
|
|
220
|
+
...(languages ? { "intl.accept_languages": languages.join(",") } : {}),
|
|
221
|
+
...(proxy ? FIREFOX_PROXY_PREFS : {}),
|
|
222
|
+
};
|
|
223
|
+
context = await firefox.launchPersistentContext(dir, {
|
|
224
|
+
executablePath: found.path,
|
|
225
|
+
headless: config.browser.launchOptions.headless ?? false,
|
|
226
|
+
...(config.browser.contextOptions ?? {}),
|
|
227
|
+
...(proxy ? { proxy } : {}),
|
|
228
|
+
...(tz ? { timezoneId: tz } : {}),
|
|
229
|
+
...(Object.keys(prefs).length ? { firefoxUserPrefs: prefs } : {}),
|
|
230
|
+
handleSIGINT: false,
|
|
231
|
+
handleSIGTERM: false,
|
|
232
|
+
env: chromeEnv(env),
|
|
233
|
+
});
|
|
234
|
+
}
|
|
235
|
+
catch (error) {
|
|
236
|
+
held?.release();
|
|
237
|
+
removeTemporary();
|
|
238
|
+
throw new Error(`could not start Camoufox: ${error.message.split("\n")[0]}`);
|
|
239
|
+
}
|
|
240
|
+
let closing = false;
|
|
241
|
+
context.once("close", () => {
|
|
242
|
+
closing = true;
|
|
243
|
+
held?.release();
|
|
244
|
+
removeTemporary();
|
|
245
|
+
});
|
|
246
|
+
let idleTimer;
|
|
247
|
+
const close = async () => {
|
|
248
|
+
upstream().core.utils.gracefullyCloseSet.delete(close);
|
|
249
|
+
idleTimer?.dispose();
|
|
250
|
+
closing = true;
|
|
251
|
+
await context.close().catch(() => { });
|
|
252
|
+
held?.release();
|
|
253
|
+
};
|
|
254
|
+
// This Playwright is not patchright-core's, so its exit hooks do not see the browser:
|
|
255
|
+
// upstream's exit watchdog awaits this close before the process exits.
|
|
256
|
+
upstream().core.utils.gracefullyCloseSet.add(close);
|
|
257
|
+
const ms = idleMs(config);
|
|
258
|
+
if (ms)
|
|
259
|
+
idleTimer = new IdleTimer(ms, () => void close());
|
|
260
|
+
return {
|
|
261
|
+
engine: "camoufox",
|
|
262
|
+
context,
|
|
263
|
+
...(idleTimer ? { idleTimer } : {}),
|
|
264
|
+
isOpen: () => !closing,
|
|
265
|
+
close,
|
|
266
|
+
};
|
|
267
|
+
},
|
|
268
|
+
};
|
|
269
|
+
}
|
|
270
|
+
//# sourceMappingURL=engine-camoufox.js.map
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { type ProcTable } from "turno-core/process";
|
|
2
|
+
import type { Engine } from "./engine.js";
|
|
3
|
+
import { type StopOptions } from "./lifecycle.js";
|
|
4
|
+
/**
|
|
5
|
+
* Read mode: the `lightpanda` engine. Lightpanda is a headless browser written from
|
|
6
|
+
* scratch for automation (no rendering, a small fraction of Chrome's memory) that speaks CDP.
|
|
7
|
+
* turno never downloads it: it runs the `lightpanda` found through `TURNO_LIGHTPANDA_PATH` or
|
|
8
|
+
* on PATH, and `turno browser doctor` says how to install it.
|
|
9
|
+
*
|
|
10
|
+
* Per launch turno starts `lightpanda serve` on a Unix socket in a fresh private folder (no TCP
|
|
11
|
+
* port), with Lightpanda's telemetry off, and connects Patchright to it through the CDP relay
|
|
12
|
+
* (`cdp-relay.ts`), in a new browser context: Lightpanda's default context holds a startup
|
|
13
|
+
* target that cannot navigate. Closing the session closes the context and stops the process.
|
|
14
|
+
*
|
|
15
|
+
* For an identity, Lightpanda keeps its own cookies in `<state>/browser/identities/<id>/
|
|
16
|
+
* lightpanda-cookies.json` (loaded at start, saved when the context closes). It never reads or
|
|
17
|
+
* writes the identity's Chrome profile, so read mode takes no runtime lock and runs no health
|
|
18
|
+
* check, challenge log, resource blocking or cache: those belong to the Chrome profile.
|
|
19
|
+
*
|
|
20
|
+
* Only the tools in `READ_MODE_TOOLS` run (the docs list them). Every other tool is refused
|
|
21
|
+
* before it reaches the browser, with the reason and a pointer to the Chrome engine.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* The tools read mode runs: each was checked against Lightpanda 1.1 (nightly) through
|
|
25
|
+
* Patchright with local pages. Clicks follow links, but a link that opens a new tab
|
|
26
|
+
* (`target="_blank"`) does nothing there.
|
|
27
|
+
*/
|
|
28
|
+
export declare const READ_MODE_TOOLS: ReadonlySet<string>;
|
|
29
|
+
/** Why read mode refuses this tool, or undefined when it runs it. */
|
|
30
|
+
export declare function readModeRefusal(tool: string): string | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* How to install Lightpanda on this platform, for errors and `turno browser doctor`: one command
|
|
33
|
+
* a person runs on macOS (Homebrew) and Linux (Lightpanda's own nightly download), the reason
|
|
34
|
+
* there is none elsewhere.
|
|
35
|
+
*/
|
|
36
|
+
export declare function lightpandaInstallHint(platform?: NodeJS.Platform, arch?: string): string;
|
|
37
|
+
export interface LightpandaInfo {
|
|
38
|
+
path: string;
|
|
39
|
+
version?: string;
|
|
40
|
+
}
|
|
41
|
+
/** The Lightpanda binary turno would run: `TURNO_LIGHTPANDA_PATH`, else `lightpanda` on PATH. */
|
|
42
|
+
export declare function findLightpanda(env?: NodeJS.ProcessEnv): LightpandaInfo | undefined;
|
|
43
|
+
/** The error when Lightpanda is missing, with the install command. */
|
|
44
|
+
export declare function lightpandaMissing(env: NodeJS.ProcessEnv): Error;
|
|
45
|
+
/** Where an identity's read mode keeps its cookies. */
|
|
46
|
+
export declare function lightpandaCookieJar(id: string, env: NodeJS.ProcessEnv): string;
|
|
47
|
+
export interface OrphanLightpanda {
|
|
48
|
+
pid: number;
|
|
49
|
+
/** The private folder of its sockets (`turno-lightpanda-*`), removed once it is gone. */
|
|
50
|
+
socketDir: string;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The `lightpanda serve` processes an earlier turno-browser-mcp left running: started by turno
|
|
54
|
+
* (a `cdp.sock` in a `turno-lightpanda-*` folder), for this identity's cookie jar (or with no
|
|
55
|
+
* jar, for a server without an identity), and with no parent left (reparented to init), so a
|
|
56
|
+
* Lightpanda that a live server drives is never touched. `"any"` finds them for every jar
|
|
57
|
+
* (`turno browser doctor`).
|
|
58
|
+
*/
|
|
59
|
+
export declare function findOrphanLightpandas(jar: string | undefined | "any", table: ProcTable): OrphanLightpanda[];
|
|
60
|
+
export interface LightpandaSweep {
|
|
61
|
+
pid: number;
|
|
62
|
+
action: "exited" | "killed" | "survived";
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Stops the Lightpanda a server killed with SIGKILL left behind (its exit handler never ran), as
|
|
66
|
+
* the Chrome sweep does for a profile: SIGTERM first, so it writes the identity's cookie jar,
|
|
67
|
+
* then SIGKILL. Runs when a server that may use read mode starts.
|
|
68
|
+
*/
|
|
69
|
+
export declare function sweepOrphanLightpandas(jar: string | undefined, opts?: StopOptions & {
|
|
70
|
+
table?: ProcTable;
|
|
71
|
+
}): Promise<LightpandaSweep[]>;
|
|
72
|
+
export declare function createLightpandaEngine(): Engine;
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
import { execFileSync, spawn } from "node:child_process";
|
|
2
|
+
import { chmodSync, existsSync, mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { basename, dirname, isAbsolute, join } from "node:path";
|
|
5
|
+
import { findOnPath } from "turno-core/paths";
|
|
6
|
+
import { parentIsInit, readProcTable } from "turno-core/process";
|
|
7
|
+
import { startCdpRelay } from "./cdp-relay.js";
|
|
8
|
+
import { IdleTimer, idleMs } from "./idle-timer.js";
|
|
9
|
+
import { identityStateDir } from "./ids.js";
|
|
10
|
+
import { stopChrome } from "./lifecycle.js";
|
|
11
|
+
import { playwright, upstream } from "./upstream.js";
|
|
12
|
+
/**
|
|
13
|
+
* Read mode: the `lightpanda` engine. Lightpanda is a headless browser written from
|
|
14
|
+
* scratch for automation (no rendering, a small fraction of Chrome's memory) that speaks CDP.
|
|
15
|
+
* turno never downloads it: it runs the `lightpanda` found through `TURNO_LIGHTPANDA_PATH` or
|
|
16
|
+
* on PATH, and `turno browser doctor` says how to install it.
|
|
17
|
+
*
|
|
18
|
+
* Per launch turno starts `lightpanda serve` on a Unix socket in a fresh private folder (no TCP
|
|
19
|
+
* port), with Lightpanda's telemetry off, and connects Patchright to it through the CDP relay
|
|
20
|
+
* (`cdp-relay.ts`), in a new browser context: Lightpanda's default context holds a startup
|
|
21
|
+
* target that cannot navigate. Closing the session closes the context and stops the process.
|
|
22
|
+
*
|
|
23
|
+
* For an identity, Lightpanda keeps its own cookies in `<state>/browser/identities/<id>/
|
|
24
|
+
* lightpanda-cookies.json` (loaded at start, saved when the context closes). It never reads or
|
|
25
|
+
* writes the identity's Chrome profile, so read mode takes no runtime lock and runs no health
|
|
26
|
+
* check, challenge log, resource blocking or cache: those belong to the Chrome profile.
|
|
27
|
+
*
|
|
28
|
+
* Only the tools in `READ_MODE_TOOLS` run (the docs list them). Every other tool is refused
|
|
29
|
+
* before it reaches the browser, with the reason and a pointer to the Chrome engine.
|
|
30
|
+
*/
|
|
31
|
+
/**
|
|
32
|
+
* The tools read mode runs: each was checked against Lightpanda 1.1 (nightly) through
|
|
33
|
+
* Patchright with local pages. Clicks follow links, but a link that opens a new tab
|
|
34
|
+
* (`target="_blank"`) does nothing there.
|
|
35
|
+
*/
|
|
36
|
+
export const READ_MODE_TOOLS = new Set([
|
|
37
|
+
"browser_navigate",
|
|
38
|
+
"browser_navigate_back",
|
|
39
|
+
"browser_snapshot",
|
|
40
|
+
"browser_find",
|
|
41
|
+
"browser_click",
|
|
42
|
+
"browser_hover",
|
|
43
|
+
"browser_type",
|
|
44
|
+
"browser_press_key",
|
|
45
|
+
"browser_select_option",
|
|
46
|
+
"browser_fill_form",
|
|
47
|
+
"browser_evaluate",
|
|
48
|
+
"browser_wait_for",
|
|
49
|
+
"browser_tabs",
|
|
50
|
+
"browser_network_requests",
|
|
51
|
+
"browser_network_request",
|
|
52
|
+
"browser_console_messages",
|
|
53
|
+
"browser_close",
|
|
54
|
+
"browser_batch",
|
|
55
|
+
// Natural language actions call only tools of this list, and read a snapshot.
|
|
56
|
+
"browser_act",
|
|
57
|
+
"browser_extract",
|
|
58
|
+
"browser_observe",
|
|
59
|
+
]);
|
|
60
|
+
/** Why read mode refuses a tool, for the tools that need more than a read. */
|
|
61
|
+
const NOT_IN_READ_MODE = {
|
|
62
|
+
browser_take_screenshot: "Lightpanda does not lay pages out, so a screenshot shows only their text; use browser_snapshot",
|
|
63
|
+
browser_resize: "Lightpanda does not lay pages out, so there is no window to resize",
|
|
64
|
+
browser_emulate_media: "Lightpanda does not lay pages out, so media emulation changes nothing visible",
|
|
65
|
+
browser_handle_dialog: "Lightpanda closes alert, confirm and prompt dialogs by itself",
|
|
66
|
+
browser_drag: "dragging needs a laid out page",
|
|
67
|
+
browser_drop: "dropping needs a laid out page",
|
|
68
|
+
browser_file_upload: "read mode does not upload files",
|
|
69
|
+
browser_run_code_unsafe: "read mode runs only the reading tools",
|
|
70
|
+
browser_login: "read mode keeps no vault sign-ins; it is meant for public pages",
|
|
71
|
+
browser_solve_captcha: "read mode runs no captcha widget to solve",
|
|
72
|
+
};
|
|
73
|
+
/** Why read mode refuses this tool, or undefined when it runs it. */
|
|
74
|
+
export function readModeRefusal(tool) {
|
|
75
|
+
if (READ_MODE_TOOLS.has(tool))
|
|
76
|
+
return undefined;
|
|
77
|
+
const why = NOT_IN_READ_MODE[tool] ?? "it was not checked against Lightpanda";
|
|
78
|
+
return (`${tool} is not available in read mode (the Lightpanda engine): ${why}. ` +
|
|
79
|
+
"Use the Chrome engine for it (`turno browser set <id> --engine chrome`, or start the server without `--engine lightpanda`).");
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* How to install Lightpanda on this platform, for errors and `turno browser doctor`: one command
|
|
83
|
+
* a person runs on macOS (Homebrew) and Linux (Lightpanda's own nightly download), the reason
|
|
84
|
+
* there is none elsewhere.
|
|
85
|
+
*/
|
|
86
|
+
export function lightpandaInstallHint(platform = process.platform, arch = process.arch) {
|
|
87
|
+
if (platform === "darwin")
|
|
88
|
+
return "brew install lightpanda-io/browser/lightpanda";
|
|
89
|
+
if (platform === "linux") {
|
|
90
|
+
const file = arch === "arm64" ? "lightpanda-aarch64-linux" : "lightpanda-x86_64-linux";
|
|
91
|
+
return `curl -fL --create-dirs -o ~/.local/bin/lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/${file} && chmod +x ~/.local/bin/lightpanda`;
|
|
92
|
+
}
|
|
93
|
+
return "Lightpanda has no build for this platform (on Windows, use WSL)";
|
|
94
|
+
}
|
|
95
|
+
/** The Lightpanda binary turno would run: `TURNO_LIGHTPANDA_PATH`, else `lightpanda` on PATH. */
|
|
96
|
+
export function findLightpanda(env = process.env) {
|
|
97
|
+
const configured = env.TURNO_LIGHTPANDA_PATH?.trim();
|
|
98
|
+
const path = configured
|
|
99
|
+
? isAbsolute(configured) && findOnPath(configured, env) && statSync(configured).isFile()
|
|
100
|
+
? configured
|
|
101
|
+
: undefined
|
|
102
|
+
: findOnPath("lightpanda", env);
|
|
103
|
+
if (!path)
|
|
104
|
+
return undefined;
|
|
105
|
+
try {
|
|
106
|
+
const out = execFileSync(path, ["version"], {
|
|
107
|
+
encoding: "utf8",
|
|
108
|
+
timeout: 5000,
|
|
109
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
110
|
+
env: { ...env, LIGHTPANDA_DISABLE_TELEMETRY: "true" },
|
|
111
|
+
}).trim();
|
|
112
|
+
return out ? { path, version: out.split("\n")[0].trim() } : { path };
|
|
113
|
+
}
|
|
114
|
+
catch {
|
|
115
|
+
return { path };
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
/** The error when Lightpanda is missing, with the install command. */
|
|
119
|
+
export function lightpandaMissing(env) {
|
|
120
|
+
const configured = env.TURNO_LIGHTPANDA_PATH?.trim();
|
|
121
|
+
const where = configured
|
|
122
|
+
? `TURNO_LIGHTPANDA_PATH (${configured}) is not an executable file with an absolute path`
|
|
123
|
+
: "lightpanda is not on PATH";
|
|
124
|
+
return new Error(`read mode needs Lightpanda, and ${where}. Install it: ${lightpandaInstallHint()}. turno never downloads it for you; \`turno browser doctor\` checks it.`);
|
|
125
|
+
}
|
|
126
|
+
/** Where an identity's read mode keeps its cookies. */
|
|
127
|
+
export function lightpandaCookieJar(id, env) {
|
|
128
|
+
return join(identityStateDir(id, env), "lightpanda-cookies.json");
|
|
129
|
+
}
|
|
130
|
+
async function waitForSocket(path, child, stderr, ms) {
|
|
131
|
+
const end = Date.now() + ms;
|
|
132
|
+
while (!existsSync(path)) {
|
|
133
|
+
if (child.exitCode !== null || child.signalCode !== null)
|
|
134
|
+
throw new Error(`lightpanda serve exited before it was ready: ${stderr().trim().split("\n").pop() ?? ""}`);
|
|
135
|
+
if (Date.now() > end)
|
|
136
|
+
throw new Error(`lightpanda serve did not start within ${ms / 1000}s`);
|
|
137
|
+
await new Promise((r) => setTimeout(r, 25));
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* A fresh private folder for the two sockets. A Unix socket path has a short limit (104 bytes
|
|
142
|
+
* on macOS), so a long TMPDIR falls back to /tmp; the folder is mode 700 either way.
|
|
143
|
+
*/
|
|
144
|
+
function socketDir(env) {
|
|
145
|
+
const base = env.TMPDIR || tmpdir();
|
|
146
|
+
const fits = join(base, "turno-lightpanda-XXXXXX", "relay.sock").length <= 100;
|
|
147
|
+
return mkdtempSync(join(fits || process.platform === "win32" ? base : "/tmp", "turno-lightpanda-"));
|
|
148
|
+
}
|
|
149
|
+
/** The arguments every `lightpanda serve` of turno starts with, up to the socket path. */
|
|
150
|
+
const SERVE = " serve --unix-socket ";
|
|
151
|
+
/** What follows the socket path in that command line. */
|
|
152
|
+
const AFTER_SOCKET = " --log-level ";
|
|
153
|
+
/**
|
|
154
|
+
* The `lightpanda serve` processes an earlier turno-browser-mcp left running: started by turno
|
|
155
|
+
* (a `cdp.sock` in a `turno-lightpanda-*` folder), for this identity's cookie jar (or with no
|
|
156
|
+
* jar, for a server without an identity), and with no parent left (reparented to init), so a
|
|
157
|
+
* Lightpanda that a live server drives is never touched. `"any"` finds them for every jar
|
|
158
|
+
* (`turno browser doctor`).
|
|
159
|
+
*/
|
|
160
|
+
export function findOrphanLightpandas(jar, table) {
|
|
161
|
+
const found = [];
|
|
162
|
+
for (const p of table.values()) {
|
|
163
|
+
const at = p.command.indexOf(SERVE);
|
|
164
|
+
if (at < 0)
|
|
165
|
+
continue;
|
|
166
|
+
const end = p.command.indexOf(AFTER_SOCKET, at + SERVE.length);
|
|
167
|
+
if (end < 0)
|
|
168
|
+
continue;
|
|
169
|
+
const socket = p.command.slice(at + SERVE.length, end);
|
|
170
|
+
const dir = dirname(socket);
|
|
171
|
+
if (basename(socket) !== "cdp.sock" || !basename(dir).startsWith("turno-lightpanda-"))
|
|
172
|
+
continue;
|
|
173
|
+
// The cookie jar is the last argument (see `launch`).
|
|
174
|
+
const forJar = jar === "any" ||
|
|
175
|
+
(jar === undefined ? !p.command.includes(" --cookie-jar ") : p.command.endsWith(` --cookie-jar ${jar}`));
|
|
176
|
+
if (!forJar || !parentIsInit(p.ppid, table))
|
|
177
|
+
continue;
|
|
178
|
+
found.push({ pid: p.pid, socketDir: dir });
|
|
179
|
+
}
|
|
180
|
+
return found;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Stops the Lightpanda a server killed with SIGKILL left behind (its exit handler never ran), as
|
|
184
|
+
* the Chrome sweep does for a profile: SIGTERM first, so it writes the identity's cookie jar,
|
|
185
|
+
* then SIGKILL. Runs when a server that may use read mode starts.
|
|
186
|
+
*/
|
|
187
|
+
export async function sweepOrphanLightpandas(jar, opts = {}) {
|
|
188
|
+
const table = opts.table ?? readProcTable();
|
|
189
|
+
if (!table)
|
|
190
|
+
return [];
|
|
191
|
+
const done = [];
|
|
192
|
+
for (const orphan of findOrphanLightpandas(jar, table)) {
|
|
193
|
+
// Spawned without a group of its own: only the process itself is signalled.
|
|
194
|
+
const action = await stopChrome({ pid: orphan.pid, pgid: -1, leaderAlive: true, owner: "orphan" }, opts);
|
|
195
|
+
if (action !== "survived")
|
|
196
|
+
rmSync(orphan.socketDir, { recursive: true, force: true });
|
|
197
|
+
done.push({ pid: orphan.pid, action });
|
|
198
|
+
}
|
|
199
|
+
return done;
|
|
200
|
+
}
|
|
201
|
+
/** Every Lightpanda this process started, stopped when it exits (an exit handler is sync). */
|
|
202
|
+
const children = new Set();
|
|
203
|
+
let exitHook = false;
|
|
204
|
+
export function createLightpandaEngine() {
|
|
205
|
+
return {
|
|
206
|
+
id: "lightpanda",
|
|
207
|
+
refuse: readModeRefusal,
|
|
208
|
+
async launch({ config, identity }) {
|
|
209
|
+
const env = identity?.env ?? process.env;
|
|
210
|
+
const found = findLightpanda(env);
|
|
211
|
+
if (!found)
|
|
212
|
+
throw lightpandaMissing(env);
|
|
213
|
+
const dir = socketDir(env);
|
|
214
|
+
chmodSync(dir, 0o700);
|
|
215
|
+
const socket = join(dir, "cdp.sock");
|
|
216
|
+
const args = ["serve", "--unix-socket", socket, "--log-level", "warn", "--cdp-max-message-size", "67108864"];
|
|
217
|
+
if (identity) {
|
|
218
|
+
mkdirSync(identityStateDir(identity.id, identity.env), { recursive: true, mode: 0o700 });
|
|
219
|
+
const jar = lightpandaCookieJar(identity.id, identity.env);
|
|
220
|
+
if (existsSync(jar))
|
|
221
|
+
args.push("--cookie", jar);
|
|
222
|
+
args.push("--cookie-jar", jar);
|
|
223
|
+
}
|
|
224
|
+
let output = "";
|
|
225
|
+
const child = spawn(found.path, args, {
|
|
226
|
+
stdio: ["ignore", "ignore", "pipe"],
|
|
227
|
+
env: { ...env, LIGHTPANDA_DISABLE_TELEMETRY: "true" },
|
|
228
|
+
});
|
|
229
|
+
child.stderr?.on("data", (d) => {
|
|
230
|
+
output = (output + d.toString()).slice(-4000);
|
|
231
|
+
});
|
|
232
|
+
children.add(child);
|
|
233
|
+
if (!exitHook) {
|
|
234
|
+
exitHook = true;
|
|
235
|
+
process.on("exit", () => {
|
|
236
|
+
for (const c of children)
|
|
237
|
+
c.kill("SIGKILL");
|
|
238
|
+
});
|
|
239
|
+
}
|
|
240
|
+
const stop = () => {
|
|
241
|
+
child.kill("SIGTERM");
|
|
242
|
+
children.delete(child);
|
|
243
|
+
rmSync(dir, { recursive: true, force: true });
|
|
244
|
+
};
|
|
245
|
+
let browser;
|
|
246
|
+
let context;
|
|
247
|
+
let relay;
|
|
248
|
+
try {
|
|
249
|
+
await waitForSocket(socket, child, () => output, 10_000);
|
|
250
|
+
relay = await startCdpRelay(join(dir, "relay.sock"), socket);
|
|
251
|
+
browser = await playwright().chromium.connectOverCDP(relay.endpoint, { timeout: 15_000 });
|
|
252
|
+
context = await browser.newContext(config.browser.contextOptions);
|
|
253
|
+
}
|
|
254
|
+
catch (error) {
|
|
255
|
+
await relay?.close().catch(() => { });
|
|
256
|
+
stop();
|
|
257
|
+
throw new Error(`could not start read mode: ${error.message.split("\n")[0]}`);
|
|
258
|
+
}
|
|
259
|
+
let closing = false;
|
|
260
|
+
child.once("exit", () => {
|
|
261
|
+
closing = true;
|
|
262
|
+
});
|
|
263
|
+
let idleTimer;
|
|
264
|
+
const close = async () => {
|
|
265
|
+
upstream().core.utils.gracefullyCloseSet.delete(close);
|
|
266
|
+
idleTimer?.dispose();
|
|
267
|
+
if (!closing || browser.isConnected()) {
|
|
268
|
+
closing = true;
|
|
269
|
+
// Closing the context is what makes Lightpanda write the cookie jar.
|
|
270
|
+
await context.close().catch(() => { });
|
|
271
|
+
await browser.close().catch(() => { });
|
|
272
|
+
}
|
|
273
|
+
await relay?.close().catch(() => { });
|
|
274
|
+
stop();
|
|
275
|
+
};
|
|
276
|
+
// The exit watchdog awaits this before the process exits: the jar is written, Lightpanda stops.
|
|
277
|
+
upstream().core.utils.gracefullyCloseSet.add(close);
|
|
278
|
+
const ms = idleMs(config);
|
|
279
|
+
if (ms)
|
|
280
|
+
idleTimer = new IdleTimer(ms, () => void close());
|
|
281
|
+
return {
|
|
282
|
+
engine: "lightpanda",
|
|
283
|
+
context,
|
|
284
|
+
...(child.pid !== undefined ? { pid: child.pid } : {}),
|
|
285
|
+
...(idleTimer ? { idleTimer } : {}),
|
|
286
|
+
isOpen: () => !closing && browser.isConnected(),
|
|
287
|
+
close,
|
|
288
|
+
};
|
|
289
|
+
},
|
|
290
|
+
};
|
|
291
|
+
}
|
|
292
|
+
//# sourceMappingURL=engine-lightpanda.js.map
|