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.
- package/CHANGELOG.md +122 -0
- package/README.md +95 -123
- package/dist/act-model.d.ts +85 -0
- package/dist/act-model.js +117 -0
- package/dist/act.d.ts +37 -0
- package/dist/act.js +600 -0
- package/dist/api.d.ts +90 -2
- package/dist/api.js +41 -4
- package/dist/argv.d.ts +16 -2
- package/dist/argv.js +100 -3
- package/dist/background-state.d.ts +54 -0
- package/dist/background-state.js +97 -0
- package/dist/background.d.ts +69 -0
- package/dist/background.js +458 -0
- package/dist/batch.d.ts +5 -0
- package/dist/batch.js +3 -3
- package/dist/bin/mcp.js +103 -6
- package/dist/captcha.d.ts +77 -0
- package/dist/captcha.js +334 -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/cli/background.d.ts +11 -0
- package/dist/cli/background.js +132 -0
- package/dist/cli/commands.d.ts +16 -0
- package/dist/cli/commands.js +515 -0
- package/dist/cli/context.d.ts +75 -0
- package/dist/cli/context.js +44 -0
- package/dist/cli/do-background.d.ts +27 -0
- package/dist/cli/do-background.js +212 -0
- package/dist/cli/do.d.ts +85 -0
- package/dist/cli/do.js +558 -0
- package/dist/cli/flows.d.ts +28 -0
- package/dist/cli/flows.js +303 -0
- package/dist/cli/identity.d.ts +37 -0
- package/dist/cli/identity.js +906 -0
- package/dist/cli/live.d.ts +7 -0
- package/dist/cli/live.js +99 -0
- package/dist/cli/main.d.ts +16 -0
- package/dist/cli/main.js +171 -0
- package/dist/cli/secret.d.ts +4 -0
- package/dist/cli/secret.js +151 -0
- package/dist/cli/session.d.ts +6 -0
- package/dist/cli/session.js +106 -0
- package/dist/cli/setup.d.ts +7 -0
- package/dist/cli/setup.js +180 -0
- package/dist/cli/vault.d.ts +5 -0
- package/dist/cli/vault.js +192 -0
- package/dist/client.d.ts +82 -0
- package/dist/client.js +303 -0
- package/dist/diagnose.d.ts +7 -0
- package/dist/diagnose.js +61 -6
- package/dist/doctor.d.ts +37 -3
- package/dist/doctor.js +264 -6
- 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 +271 -0
- package/dist/engine-lightpanda.d.ts +72 -0
- package/dist/engine-lightpanda.js +293 -0
- package/dist/engine.d.ts +63 -11
- package/dist/engine.js +106 -29
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +42 -7
- package/dist/governor.js +82 -32
- package/dist/health.js +2 -1
- package/dist/host.d.ts +38 -2
- package/dist/host.js +689 -52
- package/dist/human-input.d.ts +84 -0
- package/dist/human-input.js +448 -0
- package/dist/humanize.d.ts +123 -0
- package/dist/humanize.js +241 -0
- package/dist/identities.js +4 -1
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/index.d.ts +13 -4
- package/dist/index.js +7 -1
- package/dist/lifecycle.d.ts +11 -1
- package/dist/lifecycle.js +11 -2
- package/dist/live-client.d.ts +22 -0
- package/dist/live-client.js +95 -0
- package/dist/live-page.d.ts +4 -0
- package/dist/live-page.js +144 -0
- package/dist/live-server.d.ts +173 -0
- package/dist/live-server.js +643 -0
- package/dist/live.d.ts +120 -0
- package/dist/live.js +204 -0
- package/dist/login-tool.d.ts +13 -0
- package/dist/login-tool.js +8 -3
- package/dist/login.d.ts +4 -1
- package/dist/login.js +12 -2
- package/dist/names.d.ts +28 -0
- package/dist/names.js +25 -0
- 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 +264 -0
- package/dist/opt-in-settings.d.ts +69 -0
- package/dist/opt-in-settings.js +152 -0
- package/dist/recorder.d.ts +88 -0
- package/dist/recorder.js +538 -0
- package/dist/recordings.d.ts +116 -0
- package/dist/recordings.js +474 -0
- package/dist/redact.d.ts +7 -0
- package/dist/redact.js +18 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +383 -0
- package/dist/reputation.d.ts +24 -2
- package/dist/reputation.js +63 -17
- package/dist/runtime-lock.js +3 -2
- package/dist/session-export.js +1 -1
- package/dist/session.d.ts +10 -2
- package/dist/session.js +10 -2
- package/dist/settings.d.ts +104 -2
- package/dist/settings.js +204 -6
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -2
- package/dist/snippet.js +10 -4
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +38 -0
- package/dist/tools.js +20 -1
- package/dist/tuning.d.ts +14 -0
- package/dist/tuning.js +9 -0
- package/dist/upstream.d.ts +11 -0
- package/dist/vault.js +5 -4
- package/npm-shrinkwrap.json +6 -5
- 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
|
|
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
|
|
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
|
-
|
|
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
|
-
...(
|
|
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
|