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,458 @@
1
+ import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
2
+ import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
3
+ import { createServer } from "node:http";
4
+ import { fileURLToPath } from "node:url";
5
+ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
6
+ import { isInitializeRequest, isJSONRPCErrorResponse, isJSONRPCRequest, isJSONRPCResultResponse, } from "@modelcontextprotocol/sdk/types.js";
7
+ import { pidAlive } from "turno-core/process";
8
+ import { backgroundAlive, backgroundDir, backgroundSocketPath, backgroundStatePath, backgroundTokenPath, readBackgroundState, } from "./background-state.js";
9
+ import { shareHost } from "./host.js";
10
+ import { inUseMessage, readRuntimeLock, runtimeLockAlive } from "./runtime-lock.js";
11
+ import { SESSION_META_KEY } from "./session.js";
12
+ import { parseDuration } from "./units.js";
13
+ /**
14
+ * The background server of an identity: `turno-browser-mcp --identity <id> --background`.
15
+ *
16
+ * It serves the identity over MCP streamable HTTP, for shell use without turno's gateway
17
+ * (`client.ts` starts it, connects and calls tools). Only the user reaches it: a Unix socket in
18
+ * a folder only the user can enter, or, where a socket cannot be used (Windows, or a path longer
19
+ * than the system allows), a loopback port that asks for a random per-server bearer token kept
20
+ * in a file only the user can read. It writes `server.json` (pid, address, version) when it is
21
+ * ready and removes it when it exits.
22
+ *
23
+ * Every connection is one client session, and they all drive the identity's one browser
24
+ * (`shareHost`), as mcpd's sessions share one stdio server: with `"sharing": "tabs"` each session
25
+ * has its own tabs; with `"sharing": "session"` one session at a time holds the browser (a lease
26
+ * that ends with the session, when its owner process exits, or after `leaseMs` without a call),
27
+ * and another session's calls get an error that says so. A session continues across connections
28
+ * and processes: a client that sends its `Mcp-Session-Id` again keeps its session and its tab.
29
+ *
30
+ * It exits after `idleMs` without a request (default 15 minutes), on SIGTERM, SIGINT and SIGHUP,
31
+ * closing Chrome first. Coexistence with the stdio servers of the identity: `background-state.ts`.
32
+ */
33
+ /** Exits after this long without a request, unless the flag or TURNO_BROWSER_BACKGROUND_IDLE says otherwise. */
34
+ export const DEFAULT_BACKGROUND_IDLE_MS = 15 * 60_000;
35
+ /** With `"sharing": "session"`: how long an idle session keeps the browser (mcpd's default lease). */
36
+ const DEFAULT_LEASE_MS = 5 * 60_000;
37
+ /** The flag that turns a server into the background server, and its idle limit. */
38
+ const BACKGROUND_FLAG = "--background";
39
+ const BACKGROUND_IDLE_FLAG = "--background-idle";
40
+ const BACKGROUND_IDLE_ENV = "TURNO_BROWSER_BACKGROUND_IDLE";
41
+ /** The request header a client names the process its session belongs to with (as mcpd's). */
42
+ export const OWNER_HEADER = "x-turno-pid";
43
+ /** Longest Unix socket path (macOS allows 103 bytes, Linux 107). */
44
+ const MAX_SOCKET_PATH = 103;
45
+ const PACKAGE_VERSION = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
46
+ export class BackgroundError extends Error {
47
+ constructor(message) {
48
+ super(message);
49
+ this.name = "BackgroundError";
50
+ }
51
+ }
52
+ /** Removes `--background` and `--background-idle <duration>` from args and checks them. */
53
+ export function extractBackground(args, env = process.env) {
54
+ const rest = [];
55
+ let background = false;
56
+ let idle;
57
+ for (let i = 0; i < args.length; i++) {
58
+ const a = args[i];
59
+ if (a === BACKGROUND_FLAG)
60
+ background = true;
61
+ else if (a.startsWith(`${BACKGROUND_FLAG}=`))
62
+ throw new Error(`${BACKGROUND_FLAG} takes no value`);
63
+ else if (a === BACKGROUND_IDLE_FLAG) {
64
+ const v = args[i + 1];
65
+ if (v === undefined || v.startsWith("--"))
66
+ throw new Error(`${BACKGROUND_IDLE_FLAG} needs a duration`);
67
+ idle = v;
68
+ i++;
69
+ }
70
+ else if (a.startsWith(`${BACKGROUND_IDLE_FLAG}=`))
71
+ idle = a.slice(BACKGROUND_IDLE_FLAG.length + 1);
72
+ else
73
+ rest.push(a);
74
+ }
75
+ if (idle !== undefined && !background)
76
+ throw new Error(`${BACKGROUND_IDLE_FLAG} applies only with ${BACKGROUND_FLAG}`);
77
+ const source = idle ?? env[BACKGROUND_IDLE_ENV];
78
+ let idleMs = DEFAULT_BACKGROUND_IDLE_MS;
79
+ if (source !== undefined && source !== "") {
80
+ const ms = parseDuration(source);
81
+ if (ms === undefined)
82
+ throw new Error(`${idle !== undefined ? BACKGROUND_IDLE_FLAG : BACKGROUND_IDLE_ENV} must be a duration like "15m", "90s" or "0" (never), not "${source}"`);
83
+ idleMs = ms;
84
+ }
85
+ if (background) {
86
+ const http = rest.find((a) => ["--port", "--host"].some((f) => a === f || a.startsWith(`${f}=`)));
87
+ if (http)
88
+ throw new Error(`${BACKGROUND_FLAG} picks its own address: drop ${http.split("=")[0]}`);
89
+ }
90
+ return { background, idleMs, rest };
91
+ }
92
+ function writeState(file, state, flag) {
93
+ if (flag === "wx") {
94
+ writeFileSync(file, `${JSON.stringify(state)}\n`, { mode: 0o600, flag: "wx" });
95
+ return;
96
+ }
97
+ const tmp = `${file}.${process.pid}.tmp`;
98
+ writeFileSync(tmp, `${JSON.stringify(state)}\n`, { mode: 0o600 });
99
+ renameSync(tmp, file);
100
+ }
101
+ /** The private folder of the identity's background server, 0700 even when it existed. */
102
+ function privateDir(id, env) {
103
+ const dir = backgroundDir(id, env);
104
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
105
+ chmodSync(dir, 0o700);
106
+ return dir;
107
+ }
108
+ /**
109
+ * Takes the identity's background slot: `server.json` is created exclusively, so two servers
110
+ * started at once never both run. Refuses while another background server runs, or while
111
+ * another process holds the identity's runtime lock (its Chrome is open).
112
+ */
113
+ function claim(id, env, idleMs) {
114
+ privateDir(id, env);
115
+ const file = backgroundStatePath(id, env);
116
+ const state = {
117
+ v: 1,
118
+ pid: process.pid,
119
+ identity: id,
120
+ version: PACKAGE_VERSION,
121
+ startedAt: new Date().toISOString(),
122
+ idleMs,
123
+ };
124
+ for (let attempt = 0;; attempt++) {
125
+ try {
126
+ writeState(file, state, "wx");
127
+ break;
128
+ }
129
+ catch (err) {
130
+ if (err.code !== "EEXIST" || attempt >= 3)
131
+ throw err;
132
+ }
133
+ const other = readBackgroundState(id, env);
134
+ if (other && other.pid !== process.pid && backgroundAlive(other))
135
+ throw new BackgroundError(`the background server of browser identity "${id}" already runs (pid ${other.pid}, since ${other.startedAt})`);
136
+ rmSync(file, { force: true });
137
+ }
138
+ const lock = readRuntimeLock(id, env);
139
+ if (lock && lock.nodePid !== process.pid && runtimeLockAlive(lock)) {
140
+ rmSync(file, { force: true });
141
+ throw new BackgroundError(`${inUseMessage(id, lock)} The background server owns the identity's browser while it runs, so it starts only when no other process has it open.`);
142
+ }
143
+ return state;
144
+ }
145
+ function socketUsable(path, transport) {
146
+ if (transport === "tcp")
147
+ return false;
148
+ const fits = process.platform !== "win32" && Buffer.byteLength(path) <= MAX_SOCKET_PATH;
149
+ if (transport === "socket" && !fits)
150
+ throw new BackgroundError(`cannot use a Unix socket at ${path} on this system (path too long or no sockets)`);
151
+ return fits;
152
+ }
153
+ function listen(server, target) {
154
+ return new Promise((resolve, reject) => {
155
+ server.once("error", reject);
156
+ const done = () => {
157
+ server.off("error", reject);
158
+ resolve();
159
+ };
160
+ if (typeof target === "string")
161
+ server.listen(target, done);
162
+ else
163
+ server.listen(target.port, target.host, done);
164
+ });
165
+ }
166
+ async function readBody(req) {
167
+ const chunks = [];
168
+ let size = 0;
169
+ for await (const c of req) {
170
+ size += c.length;
171
+ if (size > 4 * 1024 * 1024)
172
+ throw new BackgroundError("request body too large");
173
+ chunks.push(c);
174
+ }
175
+ return JSON.parse(Buffer.concat(chunks).toString("utf8"));
176
+ }
177
+ function reply(res, status, message, id = null) {
178
+ if (res.headersSent)
179
+ return;
180
+ res.writeHead(status, { "content-type": "application/json" });
181
+ res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id }));
182
+ }
183
+ function clock(ms) {
184
+ return new Date(ms).toLocaleTimeString("en-US", { hour12: false });
185
+ }
186
+ function duration(ms) {
187
+ if (ms % 60_000 === 0)
188
+ return `${ms / 60_000}m`;
189
+ return `${Math.round(ms / 1000)}s`;
190
+ }
191
+ /** Serves `host` as the identity's background server until it closes. */
192
+ export async function serveBackground(host, options) {
193
+ const { identity, idleMs } = options;
194
+ const { id, env } = identity;
195
+ const log = options.log ?? ((line) => process.stderr.write(`turno-browser-mcp: ${line}\n`));
196
+ const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
197
+ const state = claim(id, env, idleMs);
198
+ const stateFile = backgroundStatePath(id, env);
199
+ const socketPath = backgroundSocketPath(id, env);
200
+ const tokenFile = backgroundTokenPath(id, env);
201
+ const useSocket = (() => {
202
+ try {
203
+ return socketUsable(socketPath, options.transport);
204
+ }
205
+ catch (error) {
206
+ rmSync(stateFile, { force: true });
207
+ throw error;
208
+ }
209
+ })();
210
+ const token = useSocket ? undefined : randomBytes(32).toString("base64url");
211
+ const shared = shareHost(host);
212
+ const sessions = new Map();
213
+ let holder;
214
+ let lastActivity = Date.now();
215
+ let active = 0;
216
+ let closing;
217
+ let resolveClosed;
218
+ const closed = new Promise((r) => {
219
+ resolveClosed = r;
220
+ });
221
+ // The files are this server's only while server.json names it.
222
+ const ours = () => readBackgroundState(id, env)?.pid === process.pid;
223
+ const removeFiles = () => {
224
+ if (!ours())
225
+ return;
226
+ rmSync(socketPath, { force: true });
227
+ rmSync(tokenFile, { force: true });
228
+ rmSync(stateFile, { force: true });
229
+ };
230
+ process.on("exit", removeFiles);
231
+ const endSession = async (s) => {
232
+ if (s.ended)
233
+ return;
234
+ s.ended = true;
235
+ sessions.delete(s.sid);
236
+ if (holder?.session === s)
237
+ holder = undefined;
238
+ await shared.endSession(s.key).catch(() => { });
239
+ };
240
+ /** With `"sharing": "session"`, why `s` may not call now, or undefined when it holds the browser. */
241
+ const leaseRefusal = (s) => {
242
+ if (options.sharing() === "tabs")
243
+ return undefined;
244
+ if (holder) {
245
+ const h = holder.session;
246
+ const gone = h.ended || (h.owner !== undefined && !pidAlive(h.owner));
247
+ const idle = h.inflight.size === 0 && Date.now() - h.lastSeen > leaseMs;
248
+ if (gone || idle)
249
+ holder = undefined;
250
+ }
251
+ if (holder && holder.session !== s) {
252
+ const h = holder.session;
253
+ return (`browser identity "${id}" is in use by another session of its background server` +
254
+ `${h.owner !== undefined ? ` (owner pid ${h.owner})` : ""} since ${clock(holder.since)}. ` +
255
+ `Try again when that session ends or after ${duration(leaseMs)} without a call from it, ` +
256
+ `or set "sharing": "tabs" in the identity's settings so that sessions share the browser in separate tabs.`);
257
+ }
258
+ if (!holder)
259
+ holder = { session: s, since: Date.now() };
260
+ return undefined;
261
+ };
262
+ /**
263
+ * Connects a new session: its calls carry its own client session in `_meta` (whatever the
264
+ * client put there), pass the lease, and count as in flight until their response leaves.
265
+ */
266
+ const openSession = async (owner) => {
267
+ let session;
268
+ const transport = new StreamableHTTPServerTransport({
269
+ sessionIdGenerator: () => randomUUID(),
270
+ onsessioninitialized: (sid) => {
271
+ session = {
272
+ sid,
273
+ key: randomUUID(),
274
+ transport,
275
+ ...(owner !== undefined ? { owner } : {}),
276
+ lastSeen: Date.now(),
277
+ inflight: new Set(),
278
+ ended: false,
279
+ };
280
+ sessions.set(sid, session);
281
+ },
282
+ onsessionclosed: async () => {
283
+ if (session)
284
+ await endSession(session);
285
+ },
286
+ });
287
+ await shared.connect(transport);
288
+ const deliver = transport.onmessage;
289
+ transport.onmessage = (message, extra) => {
290
+ const s = session;
291
+ if (s && isJSONRPCRequest(message) && message.method === "tools/call") {
292
+ s.lastSeen = Date.now();
293
+ const refusal = leaseRefusal(s);
294
+ if (refusal) {
295
+ const response = {
296
+ jsonrpc: "2.0",
297
+ id: message.id,
298
+ result: { content: [{ type: "text", text: `### Error\n${refusal}` }], isError: true },
299
+ };
300
+ void transport.send(response).catch(() => { });
301
+ return;
302
+ }
303
+ s.inflight.add(message.id);
304
+ const params = (message.params ?? {});
305
+ message.params = { ...params, _meta: { ...(params._meta ?? {}), [SESSION_META_KEY]: s.key } };
306
+ }
307
+ deliver(message, extra);
308
+ };
309
+ const send = transport.send.bind(transport);
310
+ transport.send = async (message, opts) => {
311
+ const s = session;
312
+ if (s && (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) && message.id !== undefined) {
313
+ if (s.inflight.delete(message.id))
314
+ s.lastSeen = Date.now();
315
+ }
316
+ return await send(message, opts);
317
+ };
318
+ return transport;
319
+ };
320
+ const authorized = (req, port) => {
321
+ if (!token)
322
+ return true;
323
+ // The Host check keeps a web page that rebinds a name to 127.0.0.1 out, with the token.
324
+ const hostHeader = req.headers.host ?? "";
325
+ if (hostHeader !== `127.0.0.1:${port}` && hostHeader !== `localhost:${port}`)
326
+ return false;
327
+ const auth = req.headers.authorization ?? "";
328
+ const given = Buffer.from(auth.startsWith("Bearer ") ? auth.slice(7) : "");
329
+ const expected = Buffer.from(token);
330
+ return given.length === expected.length && timingSafeEqual(given, expected);
331
+ };
332
+ const handle = async (req, res, port) => {
333
+ if (!authorized(req, port)) {
334
+ reply(res, 401, "unauthorized");
335
+ return;
336
+ }
337
+ if (new URL(req.url ?? "/", "http://localhost").pathname !== "/mcp") {
338
+ reply(res, 404, "not found");
339
+ return;
340
+ }
341
+ const sid = req.headers["mcp-session-id"];
342
+ if (typeof sid === "string") {
343
+ const s = sessions.get(sid);
344
+ if (!s) {
345
+ reply(res, 404, "Session not found");
346
+ return;
347
+ }
348
+ s.lastSeen = Date.now();
349
+ const body = req.method === "POST" ? await readBody(req) : undefined;
350
+ await s.transport.handleRequest(req, res, body);
351
+ return;
352
+ }
353
+ if (req.method !== "POST") {
354
+ reply(res, 400, "Bad Request: no session (Mcp-Session-Id)");
355
+ return;
356
+ }
357
+ const body = await readBody(req);
358
+ if (!isInitializeRequest(body)) {
359
+ reply(res, 400, "Bad Request: initialize first, or send the Mcp-Session-Id of a session");
360
+ return;
361
+ }
362
+ const raw = req.headers[OWNER_HEADER];
363
+ const owner = typeof raw === "string" && /^\d{1,10}$/.test(raw) && Number(raw) > 1 ? Number(raw) : undefined;
364
+ const transport = await openSession(owner);
365
+ await transport.handleRequest(req, res, body);
366
+ };
367
+ const http = createServer((req, res) => {
368
+ // A request in flight keeps the server up; an open event stream (GET) does not.
369
+ const counts = req.method !== "GET";
370
+ lastActivity = Date.now();
371
+ if (counts)
372
+ active++;
373
+ res.once("close", () => {
374
+ lastActivity = Date.now();
375
+ if (counts)
376
+ active--;
377
+ });
378
+ const port = http.address()?.port ?? 0;
379
+ handle(req, res, port).catch((error) => {
380
+ if (error instanceof SyntaxError)
381
+ reply(res, 400, "Parse error");
382
+ else
383
+ reply(res, 500, error.message);
384
+ });
385
+ });
386
+ // A tool call may take longer than Node's default request timeout of 5 minutes.
387
+ http.requestTimeout = 0;
388
+ try {
389
+ if (useSocket) {
390
+ rmSync(socketPath, { force: true });
391
+ await listen(http, socketPath);
392
+ chmodSync(socketPath, 0o600);
393
+ }
394
+ else {
395
+ await listen(http, { port: 0, host: "127.0.0.1" });
396
+ writeFileSync(tokenFile, `${token}\n`, { mode: 0o600 });
397
+ chmodSync(tokenFile, 0o600);
398
+ }
399
+ }
400
+ catch (error) {
401
+ removeFiles();
402
+ throw error;
403
+ }
404
+ const ready = useSocket
405
+ ? { ...state, transport: "socket", socket: socketPath }
406
+ : { ...state, transport: "tcp", port: http.address().port, tokenFile };
407
+ writeState(stateFile, ready, "w");
408
+ const close = (reason = "closed") => {
409
+ closing ??= (async () => {
410
+ log(`background server of "${id}" stops: ${reason}`);
411
+ clearInterval(sweep);
412
+ http.close();
413
+ http.closeAllConnections();
414
+ for (const s of [...sessions.values()]) {
415
+ await endSession(s);
416
+ await s.transport.close().catch(() => { });
417
+ }
418
+ await shared.dispose().catch(() => { });
419
+ removeFiles();
420
+ process.off("exit", removeFiles);
421
+ resolveClosed();
422
+ (options.onClosed ?? (() => process.exit(0)))(reason);
423
+ })();
424
+ return closing;
425
+ };
426
+ const sweepMs = options.sweepMs ?? Math.min(15_000, Math.max(100, Math.floor((idleMs || 60_000) / 4)));
427
+ const sweep = setInterval(() => {
428
+ for (const s of [...sessions.values()])
429
+ if (s.owner !== undefined && s.inflight.size === 0 && !pidAlive(s.owner)) {
430
+ void endSession(s);
431
+ void s.transport.close().catch(() => { });
432
+ }
433
+ if (!ours())
434
+ void close("its state file was replaced or removed");
435
+ else if (idleMs > 0 && active === 0 && Date.now() - lastActivity >= idleMs)
436
+ void close(`no request for ${duration(idleMs)}`);
437
+ }, sweepMs);
438
+ if (options.signals !== false)
439
+ for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
440
+ process.once(signal, () => void close(signal));
441
+ log(`background server of "${id}" ready on ${useSocket ? socketPath : `127.0.0.1:${ready.port} (token in ${tokenFile})`}` +
442
+ `${idleMs > 0 ? `; exits after ${duration(idleMs)} without a request` : ""}`);
443
+ return { state: ready, close, closed };
444
+ }
445
+ /** The identity's sharing mode for the lease: `--sharing`, else identity.json, else "session". */
446
+ export function sharingOf(flag, read) {
447
+ return () => {
448
+ if (flag)
449
+ return flag;
450
+ try {
451
+ return read() ?? "session";
452
+ }
453
+ catch {
454
+ return "session"; // a bad identity.json: the launch reports it
455
+ }
456
+ };
457
+ }
458
+ //# sourceMappingURL=background.js.map
package/dist/batch.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { TurnoTool } from "./tools.js";
2
+ import { type ToolResult } from "./upstream.js";
2
3
  /**
3
4
  * `browser_batch`: several stock actions in one tool call. Each action runs through
4
5
  * the same path as a call of its own (the tab governor, the click diagnosis), but without the
@@ -10,5 +11,9 @@ import type { TurnoTool } from "./tools.js";
10
11
  */
11
12
  /** Most actions in one batch. */
12
13
  export declare const MAX_BATCH = 20;
14
+ /** The sections of an upstream result text (`### Title` then the body). */
15
+ export declare function sections(text: string): Map<string, string>;
16
+ export declare function clip(text: string, max?: number): string;
17
+ export declare function textOf(result: ToolResult): string;
13
18
  /** The tool. Its schema is built on first use, so importing the registry does not load the bundle. */
14
19
  export declare function batchTool(): TurnoTool;
package/dist/batch.js CHANGED
@@ -13,7 +13,7 @@ export const MAX_BATCH = 20;
13
13
  /** Longest text kept from one action's result section. */
14
14
  const RESULT_CHARS = 400;
15
15
  /** The sections of an upstream result text (`### Title` then the body). */
16
- function sections(text) {
16
+ export function sections(text) {
17
17
  const out = new Map();
18
18
  for (const part of text.split(/^### /m).slice(1)) {
19
19
  const nl = part.indexOf("\n");
@@ -23,7 +23,7 @@ function sections(text) {
23
23
  }
24
24
  return out;
25
25
  }
26
- function clip(text, max = RESULT_CHARS) {
26
+ export function clip(text, max = RESULT_CHARS) {
27
27
  return text.length > max ? `${text.slice(0, max - 3)}...` : text;
28
28
  }
29
29
  /** What an action acted on, for its line: `browser_click e5`, `browser_navigate https://...`. */
@@ -31,7 +31,7 @@ function label(tool, args) {
31
31
  const what = args.target ?? args.startTarget ?? args.url ?? args.key ?? args.action ?? args.text;
32
32
  return what === undefined ? tool : `${tool} ${clip(String(what), 80)}`;
33
33
  }
34
- function textOf(result) {
34
+ export function textOf(result) {
35
35
  return result.content
36
36
  .filter((c) => c.type === "text")
37
37
  .map((c) => c.text)
package/dist/bin/mcp.js CHANGED
@@ -2,8 +2,12 @@
2
2
  import { mkdirSync, rmSync, writeFileSync } from "node:fs";
3
3
  import { dirname } from "node:path";
4
4
  import { buildArgv } from "../argv.js";
5
+ import { extractBackground, serveBackground, sharingOf } from "../background.js";
6
+ import { engineChoice } from "../engine.js";
7
+ import { lightpandaCookieJar, sweepOrphanLightpandas } from "../engine-lightpanda.js";
5
8
  import { runHost } from "../host.js";
6
9
  import { installShutdownGuard, sweepOrphan } from "../lifecycle.js";
10
+ import { readIdentitySettings } from "../settings.js";
7
11
  /**
8
12
  * turno-browser-mcp [--identity <id>] [playwright-mcp flags]
9
13
  *
@@ -12,12 +16,14 @@ import { installShutdownGuard, sweepOrphan } from "../lifecycle.js";
12
16
  * Chrome an earlier run left behind on the same profile, and a deadline on shutdown. With
13
17
  * `--identity`, the identity module: identity.json applied at launch,
14
18
  * a runtime lock while Chrome runs, the session health check and the reputation log.
15
- * Speaks MCP over stdio; `--port` with `--identity` needs `--allow-http-identity`.
19
+ * Speaks MCP over stdio; `--port` with `--identity` needs `--allow-http-identity`; `--background`
20
+ * serves the identity to the shell from a private socket (`background.ts`).
16
21
  */
17
22
  const HELP = `turno-browser-mcp: a browser MCP server that drives your installed Chrome, with one
18
- persistent profile per identity (turno identity add browser:<id>).
23
+ persistent profile per identity (turno-browser add <id>).
19
24
 
20
- --identity <id> use the identity's saved profile (served one session at a time by mcpd)
25
+ --identity <id> use the identity's saved profile (served one session at a time by
26
+ mcpd, unless the identity's "sharing" is "tabs")
21
27
  --allow-http-identity allow --port or --host together with --identity; the server then
22
28
  binds to 127.0.0.1 only. Any local process can use that browser.
23
29
 
@@ -34,11 +40,60 @@ Tabs (these flags win over the identity's identity.json):
34
40
  --close-after <duration> close a page unused this long (default 15m; 0: never)
35
41
  --background-throttling let Chrome slow down tabs that are not in front (default off); the
36
42
  agent's tab is brought to the front before each call
43
+ --sharing <session|tabs> "tabs": several agent sessions use the browser at once, each in
44
+ its own tabs, which it locks (default "session", one at a time;
45
+ mcp.toml then needs exclusive = false for this server)
46
+
47
+ Input (wins over the identity's identity.json):
48
+ --humanize <level> off (default), light, full or adaptive: the pointer travels a curve
49
+ to a point inside the target, keys are typed with human delays;
50
+ full adds overshoot, reading pauses and wheel scrolling; adaptive is
51
+ light, and full on a site that showed a challenge page
52
+
53
+ Engines (these flags win over the identity's identity.json; all off by default):
54
+ --engine lightpanda read mode: Lightpanda instead of Chrome, for reading pages
55
+ (navigate, snapshot, find, click a link, evaluate); other tools are
56
+ refused. Needs lightpanda on PATH or TURNO_LIGHTPANDA_PATH
57
+ --engine camoufox Camoufox (a Firefox build) instead of Chrome, with its own profile;
58
+ off by default. Needs Camoufox and
59
+ playwright-core (turno-browser doctor says how); never downloaded
60
+ --engine chrome the default; turns off an identity's read, Camoufox or attach mode
61
+ --attach <target> connect to a Chrome you already have open instead of launching
62
+ one: "auto" (your default Chrome profile, after you turn on remote
63
+ debugging at chrome://inspect/#remote-debugging), a Chrome user
64
+ data dir, or a loopback endpoint. The agent sees every window of
65
+ that profile; turno closes only the tabs it opened
66
+
67
+ Live view (wins over the identity's identity.json; off by default):
68
+ --live serve a view of the agent's tab on 127.0.0.1 (turno-browser live
69
+ <id> opens it) and let you pause the agent to take the controls
70
+ --live-wait <duration> how long a call waits while you have the agent paused (default 2m,
71
+ "5s" to "30m"); then it fails and tells the agent you still have it
72
+
73
+ Background server (for shell use without turno; turno-browser do starts it):
74
+ --background serve the identity over MCP streamable HTTP on a Unix socket in a
75
+ folder only you can enter (<state>/browser/identities/<id>/background),
76
+ or on 127.0.0.1 with a per-server token in a file only you can read
77
+ where a socket cannot be used. Writes server.json there while it runs.
78
+ Needs --identity; --port and --host do not apply
79
+ --background-idle <duration>
80
+ exit after this long without a request (default 15m; "0" never);
81
+ also TURNO_BROWSER_BACKGROUND_IDLE. Chrome closes first
82
+ While the background server of an identity runs, it alone drives the identity's browser: a
83
+ stdio server of that identity (an agent's, or mcpd's) answers each call that needs the browser
84
+ with an error that names the background server, and the background server does not start while
85
+ another process has the identity's Chrome open. Stop it with turno-browser background stop <id>
86
+ (or kill <pid>); turno-browser background shows which run.
37
87
 
38
88
  Examples:
39
89
  turno-browser-mcp --identity work
40
90
  turno-browser-mcp --identity work --max-tabs 4 --park-after 2m
91
+ turno-browser-mcp --identity work --humanize light
41
92
  turno-browser-mcp --headless --popups keep
93
+ turno-browser-mcp --engine lightpanda
94
+ turno-browser-mcp --attach auto
95
+ turno-browser-mcp --identity work --live
96
+ turno-browser-mcp --identity work --background --background-idle 30m
42
97
 
43
98
  Every other flag is a Playwright MCP flag:
44
99
  `;
@@ -46,8 +101,12 @@ const help = process.argv.includes("--help") || process.argv.includes("-h");
46
101
  if (help)
47
102
  process.stdout.write(`${HELP}\n`);
48
103
  let built;
104
+ let background;
49
105
  try {
50
- built = buildArgv(process.argv.slice(2));
106
+ background = extractBackground(process.argv.slice(2));
107
+ built = buildArgv(background.rest);
108
+ if (background.background && built.identity === undefined)
109
+ throw new Error("--background needs --identity <id>: it serves one identity's browser");
51
110
  }
52
111
  catch (err) {
53
112
  process.stderr.write(`turno-browser-mcp: ${err.message}\n`);
@@ -71,10 +130,48 @@ if (built.userDataDir && !help) {
71
130
  else if (swept.action === "survived") {
72
131
  process.stderr.write(`turno-browser-mcp: a Chrome an earlier run left open on this profile (pid ${swept.pid}) did not stop\n`);
73
132
  }
74
- installShutdownGuard(built.userDataDir);
133
+ installShutdownGuard(built.userDataDir, { stdin: !background.background });
134
+ }
135
+ if (!help && readMode(built)) {
136
+ const jar = built.identity !== undefined ? lightpandaCookieJar(built.identity, process.env) : undefined;
137
+ for (const swept of await sweepOrphanLightpandas(jar)) {
138
+ process.stderr.write(swept.action === "survived"
139
+ ? `turno-browser-mcp: a Lightpanda an earlier run left open (pid ${swept.pid}) did not stop\n`
140
+ : `turno-browser-mcp: closed a Lightpanda an earlier run left open (pid ${swept.pid})\n`);
141
+ }
142
+ }
143
+ /** True when this server runs on Lightpanda (`--engine lightpanda`, or the identity's engine). */
144
+ function readMode(argv) {
145
+ try {
146
+ const settings = argv.identity !== undefined ? readIdentitySettings(argv.identity, process.env) : undefined;
147
+ return engineChoice(argv.engineFlags ?? {}, settings).kind === "lightpanda";
148
+ }
149
+ catch {
150
+ return false; // the launch reports a bad identity.json or flag
151
+ }
75
152
  }
153
+ const identity = built.identity !== undefined ? { id: built.identity, env: process.env } : undefined;
76
154
  await runHost(built.args, {
77
- ...(built.identity !== undefined ? { identity: { id: built.identity, env: process.env } } : {}),
155
+ ...(identity ? { identity } : {}),
78
156
  ...(built.tuning ? { tuning: built.tuning } : {}),
157
+ ...(built.engineFlags ? { engineFlags: built.engineFlags } : {}),
158
+ ...(built.live ? { live: built.live } : {}),
159
+ ...(background.background && identity
160
+ ? {
161
+ serve: async (host) => {
162
+ try {
163
+ await serveBackground(host, {
164
+ identity,
165
+ idleMs: background.idleMs,
166
+ sharing: sharingOf(built.tuning?.sharing, () => readIdentitySettings(identity.id, identity.env)?.sharing),
167
+ });
168
+ }
169
+ catch (err) {
170
+ process.stderr.write(`turno-browser-mcp: ${err.message}\n`);
171
+ process.exit(1);
172
+ }
173
+ },
174
+ }
175
+ : {}),
79
176
  });
80
177
  //# sourceMappingURL=mcp.js.map