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