turno-browser 0.2.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 +228 -0
- package/README.md +205 -16
- 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 +96 -0
- package/dist/api.js +88 -0
- package/dist/argv.d.ts +55 -3
- package/dist/argv.js +190 -10
- package/dist/batch.d.ts +19 -0
- package/dist/batch.js +148 -0
- package/dist/bench.d.ts +1 -1
- package/dist/bench.js +21 -5
- package/dist/bin/mcp.js +108 -12
- 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/detectors.d.ts +11 -0
- package/dist/detectors.js +46 -4
- package/dist/diagnose.d.ts +45 -0
- package/dist/diagnose.js +326 -0
- package/dist/doctor.d.ts +85 -0
- package/dist/doctor.js +556 -0
- 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 +119 -0
- package/dist/engine.js +355 -0
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +119 -0
- package/dist/governor.js +325 -0
- package/dist/health.d.ts +60 -0
- package/dist/health.js +86 -0
- package/dist/host.d.ts +95 -0
- package/dist/host.js +1181 -0
- 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.d.ts +23 -10
- package/dist/identities.js +45 -37
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/ids.d.ts +9 -0
- package/dist/ids.js +34 -0
- package/dist/index.d.ts +21 -6
- package/dist/index.js +19 -18
- package/dist/lifecycle.d.ts +99 -0
- package/dist/lifecycle.js +172 -0
- 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 +45 -0
- package/dist/login-tool.js +233 -0
- package/dist/login.d.ts +8 -3
- package/dist/login.js +65 -26
- 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/patchright.d.ts +4 -2
- package/dist/patchright.js +4 -2
- 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 +34 -0
- package/dist/redact.js +135 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +382 -0
- package/dist/reputation.d.ts +89 -0
- package/dist/reputation.js +203 -0
- package/dist/resources.d.ts +76 -0
- package/dist/resources.js +341 -0
- package/dist/runtime-lock.d.ts +59 -0
- package/dist/runtime-lock.js +131 -0
- package/dist/sealed.d.ts +8 -0
- package/dist/sealed.js +96 -0
- package/dist/session-export.d.ts +67 -0
- package/dist/session-export.js +194 -0
- package/dist/session.d.ts +20 -0
- package/dist/session.js +30 -0
- package/dist/settings.d.ts +246 -0
- package/dist/settings.js +530 -0
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -0
- package/dist/snippet.js +22 -0
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +111 -0
- package/dist/tools.js +59 -0
- package/dist/totp.d.ts +32 -0
- package/dist/totp.js +82 -0
- package/dist/tuning.d.ts +76 -0
- package/dist/tuning.js +69 -0
- package/dist/units.d.ts +8 -0
- package/dist/units.js +20 -0
- package/dist/upstream.d.ts +243 -0
- package/dist/upstream.js +46 -0
- package/dist/vault.d.ts +91 -0
- package/dist/vault.js +273 -0
- package/npm-shrinkwrap.json +1074 -3
- package/package.json +5 -4
- package/dist/paths.d.ts +0 -17
- package/dist/paths.js +0 -17
|
@@ -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
|
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import type { BrowserContext, Page } from "patchright-core";
|
|
2
|
+
import { type AttachTarget } from "./engine-attach.js";
|
|
3
|
+
import { type IdentitySettings } from "./settings.js";
|
|
4
|
+
import { type Tuning } from "./tuning.js";
|
|
5
|
+
import { type ClientInfo, type IdleTimerLike, type McpConfig } from "./upstream.js";
|
|
6
|
+
/**
|
|
7
|
+
* Where the browser context behind an MCP session comes from. The host asks an
|
|
8
|
+
* engine for a context when a session first needs the browser, and again after the browser
|
|
9
|
+
* closed (idle limit, `browser_close`); it never launches a browser any other way. This module
|
|
10
|
+
* and the `engine-*.ts` modules are the only code that knows how each engine starts.
|
|
11
|
+
*
|
|
12
|
+
* - `chrome`: the default. turno launches the installed Chrome itself, as a Patchright
|
|
13
|
+
* persistent context on the profile it chose (the identity's, or a temporary one), with the
|
|
14
|
+
* launch options upstream would use, so the profile and the tools see the same browser.
|
|
15
|
+
* - `upstream`: every other mode (`--isolated`, `--cdp-endpoint`, `--endpoint`, `--extension`,
|
|
16
|
+
* `--shared-browser-context`, another browser than Chromium), handed to upstream's
|
|
17
|
+
* `createBrowserWithInfo` exactly as the stock program does.
|
|
18
|
+
* - `lightpanda`: read mode on Lightpanda (`engine-lightpanda.ts`), chosen explicitly.
|
|
19
|
+
* - `attach`: the Chrome the user already has open (`engine-attach.ts`), chosen explicitly.
|
|
20
|
+
* - `camoufox`: Camoufox, a Firefox build, on stock Playwright (`engine-camoufox.ts`), chosen
|
|
21
|
+
* explicitly.
|
|
22
|
+
*
|
|
23
|
+
* Which one runs is decided at every launch (`engineChoice`): a server flag (`--engine`,
|
|
24
|
+
* `--attach`) wins over identity.json (`engine`, `attach`), which is read at every launch like
|
|
25
|
+
* the rest of it; without either, the config decides between `chrome` and `upstream`. Another
|
|
26
|
+
* engine is one more `Engine` and one more case in `createEngine`; the host only sees
|
|
27
|
+
* `LaunchedBrowser`.
|
|
28
|
+
*/
|
|
29
|
+
type EngineId = "chrome" | "upstream" | "lightpanda" | "attach" | "camoufox";
|
|
30
|
+
export interface LaunchedBrowser {
|
|
31
|
+
engine: EngineId;
|
|
32
|
+
/** The context the tools drive. */
|
|
33
|
+
context: BrowserContext;
|
|
34
|
+
/** The browser process, when turno started it and can name it. */
|
|
35
|
+
pid?: number;
|
|
36
|
+
/** Closes the session's browser (or leaves a shared one to the last session). */
|
|
37
|
+
close(): Promise<void>;
|
|
38
|
+
/**
|
|
39
|
+
* False once the browser started closing (idle limit, a crash). Playwright may report the
|
|
40
|
+
* close a moment after Chrome has exited, so the host asks before reusing a browser.
|
|
41
|
+
*/
|
|
42
|
+
isOpen(): boolean;
|
|
43
|
+
/** Closes the browser after the configured time without a tool call. */
|
|
44
|
+
idleTimer?: IdleTimerLike;
|
|
45
|
+
/**
|
|
46
|
+
* True when the browser is the user's own (attach mode): the host opens a tab of its own as
|
|
47
|
+
* the current tab, the tab governor touches only the agent's tabs, and nothing is brought to
|
|
48
|
+
* the front.
|
|
49
|
+
*/
|
|
50
|
+
userBrowser?: boolean;
|
|
51
|
+
/** Marks a page as opened by the agent, so `close` closes it (attach mode). */
|
|
52
|
+
own?(page: Page): void;
|
|
53
|
+
}
|
|
54
|
+
export interface LaunchRequest {
|
|
55
|
+
config: McpConfig;
|
|
56
|
+
clientInfo: ClientInfo;
|
|
57
|
+
/** The parsed command line options (upstream reads `--extension` details from them). */
|
|
58
|
+
cliOptions: Record<string, unknown>;
|
|
59
|
+
/** The session title the browser is bound under (`browser.bind`), "<client> (2)" for a second one. */
|
|
60
|
+
title: string;
|
|
61
|
+
/** The identity whose profile this is (`--identity`), for its settings and runtime lock. */
|
|
62
|
+
identity?: IdentityRef;
|
|
63
|
+
/** How to run this browser; the chrome engine applies `backgroundThrottling`. */
|
|
64
|
+
tuning?: Tuning;
|
|
65
|
+
/** Hides a secret the launch read (proxy credentials) from every tool result. */
|
|
66
|
+
secret?: (value: string, label: string) => void;
|
|
67
|
+
}
|
|
68
|
+
/** A browser identity as the host knows it: its id and the environment that locates its files. */
|
|
69
|
+
export interface IdentityRef {
|
|
70
|
+
id: string;
|
|
71
|
+
env: NodeJS.ProcessEnv;
|
|
72
|
+
}
|
|
73
|
+
export interface Engine {
|
|
74
|
+
id: EngineId;
|
|
75
|
+
launch(request: LaunchRequest): Promise<LaunchedBrowser>;
|
|
76
|
+
/**
|
|
77
|
+
* Why this engine does not run a tool, checked before the call reaches (or launches) the
|
|
78
|
+
* browser; undefined when it runs it. For the identity's engine, `identity` says which one.
|
|
79
|
+
*/
|
|
80
|
+
refuse?(tool: string, identity?: IdentityRef): string | undefined;
|
|
81
|
+
}
|
|
82
|
+
/** True when the config asks for the browser the `chrome` engine launches. */
|
|
83
|
+
export declare function usesChromeEngine(config: McpConfig): boolean;
|
|
84
|
+
/** The engine for this config. */
|
|
85
|
+
export declare function selectEngine(config: McpConfig, fallback: Engine): Engine;
|
|
86
|
+
/** The `turno-browser-mcp` flags that pick an engine; each wins over identity.json. */
|
|
87
|
+
export interface EngineFlags {
|
|
88
|
+
engine?: "chrome" | "lightpanda" | "camoufox";
|
|
89
|
+
/** An attach target (`parseAttachTarget`). */
|
|
90
|
+
attach?: string;
|
|
91
|
+
}
|
|
92
|
+
/** The engine one launch uses, before the config decides between `chrome` and `upstream`. */
|
|
93
|
+
export type EngineChoice = {
|
|
94
|
+
kind: "default";
|
|
95
|
+
} | {
|
|
96
|
+
kind: "lightpanda";
|
|
97
|
+
} | {
|
|
98
|
+
kind: "camoufox";
|
|
99
|
+
} | {
|
|
100
|
+
kind: "attach";
|
|
101
|
+
target: AttachTarget;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Flags first, then identity.json. A flag of either kind replaces both keys of identity.json:
|
|
105
|
+
* `--engine chrome` turns an identity's attach or read mode off for that server.
|
|
106
|
+
*/
|
|
107
|
+
export declare function engineChoice(flags: EngineFlags, settings: Pick<IdentitySettings, "engine" | "attach"> | undefined): EngineChoice;
|
|
108
|
+
/**
|
|
109
|
+
* The host's engine: at every launch it reads the identity's settings and the flags, and hands
|
|
110
|
+
* the launch to `lightpanda`, `attach`, or the engine the config selects.
|
|
111
|
+
*/
|
|
112
|
+
/**
|
|
113
|
+
* Why an engine cannot run with these settings, if it cannot: attach mode keeps one agent's tabs
|
|
114
|
+
* apart from the user's, not several sessions apart from each other, and read mode has no
|
|
115
|
+
* layout for human-like input to move over.
|
|
116
|
+
*/
|
|
117
|
+
export declare function tuningClash(engine: string, tuning: Pick<Tuning, "sharing" | "humanize">): string | undefined;
|
|
118
|
+
export declare function createEngine(config: McpConfig, flags?: EngineFlags, fallback?: Engine): Engine;
|
|
119
|
+
export {};
|