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
package/dist/client.js
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { closeSync, openSync, readFileSync, statSync, truncateSync } from "node:fs";
|
|
3
|
+
import { request as httpRequest } from "node:http";
|
|
4
|
+
import { Readable } from "node:stream";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
7
|
+
import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
|
|
8
|
+
import { ensurePrivateDir } from "turno-core/paths";
|
|
9
|
+
import { pidAlive } from "turno-core/process";
|
|
10
|
+
import { BackgroundError, OWNER_HEADER } from "./background.js";
|
|
11
|
+
import { backgroundDir, backgroundLogPath, liveBackground, readBackgroundState, removeBackgroundFiles, } from "./background-state.js";
|
|
12
|
+
import { assertIdentityId } from "./ids.js";
|
|
13
|
+
/**
|
|
14
|
+
* The client of an identity's background server (`background.ts`): start it when it is not
|
|
15
|
+
* running, open or continue an MCP session on it, call tools, end the session, stop the server.
|
|
16
|
+
* `turno-browser do` uses it when turno's gateway is not there.
|
|
17
|
+
*
|
|
18
|
+
* A session is the unit that keeps a tab: with `"sharing": "tabs"` each session has its own tabs,
|
|
19
|
+
* with `"sharing": "session"` one session at a time holds the browser. To continue a session from
|
|
20
|
+
* another process, save `id` and `protocolVersion` of an open one and pass them as `session`; a
|
|
21
|
+
* session the server no longer knows (it restarted) is replaced by a new one (`resumed: false`).
|
|
22
|
+
*/
|
|
23
|
+
export { BackgroundError } from "./background.js";
|
|
24
|
+
const DEFAULT_START_TIMEOUT_MS = 30_000;
|
|
25
|
+
const DEFAULT_CALL_TIMEOUT_MS = 120_000;
|
|
26
|
+
/** A log longer than this is cut when a server starts. */
|
|
27
|
+
const MAX_LOG_BYTES = 1024 * 1024;
|
|
28
|
+
function envOf(options) {
|
|
29
|
+
return options?.env ?? process.env;
|
|
30
|
+
}
|
|
31
|
+
/** The running background server of the identity, or undefined (a state left by a killed one is removed). */
|
|
32
|
+
export function backgroundStatus(id, options) {
|
|
33
|
+
assertIdentityId(id);
|
|
34
|
+
const state = liveBackground(id, envOf(options));
|
|
35
|
+
return state?.transport ? state : undefined;
|
|
36
|
+
}
|
|
37
|
+
function defaultBin() {
|
|
38
|
+
return fileURLToPath(new URL("./bin/mcp.js", import.meta.url));
|
|
39
|
+
}
|
|
40
|
+
function logTail(file, lines = 8) {
|
|
41
|
+
try {
|
|
42
|
+
return readFileSync(file, "utf8").trimEnd().split("\n").slice(-lines).join("\n");
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
return "";
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
49
|
+
/**
|
|
50
|
+
* Starts the identity's background server unless it runs: detached from this process, its
|
|
51
|
+
* output in `server.log` of its folder. Resolves when it is ready; rejects with what it wrote
|
|
52
|
+
* when it exits first (the identity is in use, a bad flag) or after the timeout.
|
|
53
|
+
*/
|
|
54
|
+
export async function startBackground(id, options = {}) {
|
|
55
|
+
assertIdentityId(id);
|
|
56
|
+
const env = envOf(options);
|
|
57
|
+
const running = backgroundStatus(id, options);
|
|
58
|
+
if (running)
|
|
59
|
+
return { state: running, started: false };
|
|
60
|
+
// Files the server saves (snapshots, downloads) land in its private folder, not where it was started.
|
|
61
|
+
const dir = ensurePrivateDir(backgroundDir(id, env), env);
|
|
62
|
+
const logFile = backgroundLogPath(id, env);
|
|
63
|
+
try {
|
|
64
|
+
if (statSync(logFile).size > MAX_LOG_BYTES)
|
|
65
|
+
truncateSync(logFile, 0);
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
/* no log yet */
|
|
69
|
+
}
|
|
70
|
+
const fd = openSync(logFile, "a", 0o600);
|
|
71
|
+
const offset = (() => {
|
|
72
|
+
try {
|
|
73
|
+
return statSync(logFile).size;
|
|
74
|
+
}
|
|
75
|
+
catch {
|
|
76
|
+
return 0;
|
|
77
|
+
}
|
|
78
|
+
})();
|
|
79
|
+
let exited;
|
|
80
|
+
try {
|
|
81
|
+
const child = spawn(process.execPath, [options.bin ?? defaultBin(), "--identity", id, "--background", ...(options.args ?? [])], { detached: true, stdio: ["ignore", fd, fd], env, cwd: dir });
|
|
82
|
+
child.once("exit", (code, signal) => {
|
|
83
|
+
exited = code ?? (signal ? -1 : null);
|
|
84
|
+
});
|
|
85
|
+
child.once("error", () => {
|
|
86
|
+
exited = -1;
|
|
87
|
+
});
|
|
88
|
+
child.unref();
|
|
89
|
+
}
|
|
90
|
+
finally {
|
|
91
|
+
closeSync(fd);
|
|
92
|
+
}
|
|
93
|
+
const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_START_TIMEOUT_MS);
|
|
94
|
+
for (;;) {
|
|
95
|
+
// Ready: this call's server, or one another call started at the same time.
|
|
96
|
+
const state = backgroundStatus(id, options);
|
|
97
|
+
if (state)
|
|
98
|
+
return { state, started: true };
|
|
99
|
+
if (exited !== undefined) {
|
|
100
|
+
const said = (() => {
|
|
101
|
+
try {
|
|
102
|
+
return readFileSync(logFile, "utf8").slice(offset).trim();
|
|
103
|
+
}
|
|
104
|
+
catch {
|
|
105
|
+
return "";
|
|
106
|
+
}
|
|
107
|
+
})();
|
|
108
|
+
throw new BackgroundError(said
|
|
109
|
+
? said.replace(/^turno-browser-mcp: /gm, "")
|
|
110
|
+
: `the background server of "${id}" exited at start (code ${exited}); see ${logFile}`);
|
|
111
|
+
}
|
|
112
|
+
if (Date.now() > deadline)
|
|
113
|
+
throw new BackgroundError(`the background server of "${id}" was not ready in time; see ${logFile}${logTail(logFile) ? `:\n${logTail(logFile)}` : ""}`);
|
|
114
|
+
await sleep(50);
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Stops the identity's background server (SIGTERM: it closes its sessions and Chrome, then
|
|
119
|
+
* exits). Resolves true when one ran, false when none did.
|
|
120
|
+
*/
|
|
121
|
+
export async function stopBackground(id, options = {}) {
|
|
122
|
+
assertIdentityId(id);
|
|
123
|
+
const env = envOf(options);
|
|
124
|
+
const state = liveBackground(id, env);
|
|
125
|
+
if (!state)
|
|
126
|
+
return false;
|
|
127
|
+
try {
|
|
128
|
+
process.kill(state.pid, "SIGTERM");
|
|
129
|
+
}
|
|
130
|
+
catch {
|
|
131
|
+
/* exited meanwhile */
|
|
132
|
+
}
|
|
133
|
+
const deadline = Date.now() + (options.timeoutMs ?? 10_000);
|
|
134
|
+
while (pidAlive(state.pid) && Date.now() < deadline)
|
|
135
|
+
await sleep(50);
|
|
136
|
+
if (pidAlive(state.pid)) {
|
|
137
|
+
try {
|
|
138
|
+
process.kill(state.pid, "SIGKILL"); // its Chrome is swept by the next start
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
/* gone */
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
if (readBackgroundState(id, env)?.pid === state.pid && !pidAlive(state.pid))
|
|
145
|
+
removeBackgroundFiles(id, env);
|
|
146
|
+
return true;
|
|
147
|
+
}
|
|
148
|
+
/** A fetch over the server's Unix socket. */
|
|
149
|
+
function socketFetch(socketPath) {
|
|
150
|
+
return (url, init = {}) => new Promise((resolve, reject) => {
|
|
151
|
+
const target = new URL(url);
|
|
152
|
+
const headers = {};
|
|
153
|
+
new Headers(init.headers).forEach((value, key) => {
|
|
154
|
+
headers[key] = value;
|
|
155
|
+
});
|
|
156
|
+
const req = httpRequest({ socketPath, path: `${target.pathname}${target.search}`, method: init.method ?? "GET", headers }, (res) => {
|
|
157
|
+
const out = new Headers();
|
|
158
|
+
for (const [key, value] of Object.entries(res.headers)) {
|
|
159
|
+
if (Array.isArray(value))
|
|
160
|
+
for (const v of value)
|
|
161
|
+
out.append(key, v);
|
|
162
|
+
else if (value !== undefined)
|
|
163
|
+
out.set(key, value);
|
|
164
|
+
}
|
|
165
|
+
const status = res.statusCode ?? 500;
|
|
166
|
+
const empty = status === 204 || status === 304 || init.method === "HEAD";
|
|
167
|
+
if (empty)
|
|
168
|
+
res.resume();
|
|
169
|
+
resolve(new Response(empty ? null : Readable.toWeb(res), {
|
|
170
|
+
status,
|
|
171
|
+
statusText: res.statusMessage ?? "",
|
|
172
|
+
headers: out,
|
|
173
|
+
}));
|
|
174
|
+
});
|
|
175
|
+
const signal = init.signal;
|
|
176
|
+
const abort = () => req.destroy(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
|
|
177
|
+
if (signal?.aborted) {
|
|
178
|
+
abort();
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
signal?.addEventListener("abort", abort, { once: true });
|
|
182
|
+
req.once("error", reject);
|
|
183
|
+
if (typeof init.body === "string" || init.body instanceof Uint8Array)
|
|
184
|
+
req.end(init.body);
|
|
185
|
+
else
|
|
186
|
+
req.end();
|
|
187
|
+
});
|
|
188
|
+
}
|
|
189
|
+
function transportFor(state, owner, session) {
|
|
190
|
+
const headers = owner !== undefined ? { [OWNER_HEADER]: String(owner) } : {};
|
|
191
|
+
let url;
|
|
192
|
+
let fetch;
|
|
193
|
+
if (state.transport === "socket") {
|
|
194
|
+
url = new URL("http://localhost/mcp");
|
|
195
|
+
fetch = socketFetch(state.socket);
|
|
196
|
+
}
|
|
197
|
+
else {
|
|
198
|
+
url = new URL(`http://127.0.0.1:${state.port}/mcp`);
|
|
199
|
+
headers.Authorization = `Bearer ${readFileSync(state.tokenFile, "utf8").trim()}`;
|
|
200
|
+
}
|
|
201
|
+
const transport = new StreamableHTTPClientTransport(url, {
|
|
202
|
+
...(fetch ? { fetch } : {}),
|
|
203
|
+
...(session ? { sessionId: session.id } : {}),
|
|
204
|
+
requestInit: { headers },
|
|
205
|
+
});
|
|
206
|
+
if (session?.protocolVersion)
|
|
207
|
+
transport.setProtocolVersion(session.protocolVersion);
|
|
208
|
+
return transport;
|
|
209
|
+
}
|
|
210
|
+
function gone(err) {
|
|
211
|
+
return ((err instanceof StreamableHTTPError && err.code === 404) ||
|
|
212
|
+
/session not found/i.test(String(err?.message ?? "")));
|
|
213
|
+
}
|
|
214
|
+
function unreachable(err) {
|
|
215
|
+
const text = `${err?.message ?? ""} ${String(err?.cause ?? "")}`;
|
|
216
|
+
return /ECONNREFUSED|ENOENT|ECONNRESET|fetch failed|socket hang up/i.test(text);
|
|
217
|
+
}
|
|
218
|
+
async function connect(state, options) {
|
|
219
|
+
const name = options.clientName ?? "turno-browser";
|
|
220
|
+
if (options.session) {
|
|
221
|
+
const transport = transportFor(state, options.owner, options.session);
|
|
222
|
+
const client = new Client({ name, version: state.version }, { capabilities: {} });
|
|
223
|
+
await client.connect(transport); // a session id set: no initialize, it continues
|
|
224
|
+
try {
|
|
225
|
+
await client.ping();
|
|
226
|
+
return { client, transport, resumed: true };
|
|
227
|
+
}
|
|
228
|
+
catch (err) {
|
|
229
|
+
await client.close().catch(() => { });
|
|
230
|
+
if (!gone(err))
|
|
231
|
+
throw err;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
const transport = transportFor(state, options.owner);
|
|
235
|
+
const client = new Client({ name, version: state.version }, { capabilities: {} });
|
|
236
|
+
await client.connect(transport);
|
|
237
|
+
return { client, transport, resumed: false };
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* Opens a session on the identity's background server, or continues `options.session`,
|
|
241
|
+
* starting the server first unless `start` is false.
|
|
242
|
+
*/
|
|
243
|
+
export async function openBackgroundSession(id, options = {}) {
|
|
244
|
+
assertIdentityId(id);
|
|
245
|
+
const startOptions = options.start === false
|
|
246
|
+
? undefined
|
|
247
|
+
: { ...(typeof options.start === "object" ? options.start : {}), ...(options.env ? { env: options.env } : {}) };
|
|
248
|
+
const find = async () => {
|
|
249
|
+
if (startOptions)
|
|
250
|
+
return (await startBackground(id, startOptions)).state;
|
|
251
|
+
const state = backgroundStatus(id, options);
|
|
252
|
+
if (!state)
|
|
253
|
+
throw new BackgroundError(`the background server of browser identity "${id}" is not running`);
|
|
254
|
+
return state;
|
|
255
|
+
};
|
|
256
|
+
let state = await find();
|
|
257
|
+
let conn;
|
|
258
|
+
try {
|
|
259
|
+
conn = await connect(state, options);
|
|
260
|
+
}
|
|
261
|
+
catch (err) {
|
|
262
|
+
if (!unreachable(err))
|
|
263
|
+
throw new BackgroundError(`the background server of "${id}" refused the session: ${err.message}`);
|
|
264
|
+
// It exited between the status and the connection (its idle limit): once more, from the start.
|
|
265
|
+
await sleep(100);
|
|
266
|
+
state = await find();
|
|
267
|
+
conn = await connect(state, options).catch((again) => {
|
|
268
|
+
throw new BackgroundError(`cannot reach the background server of "${id}": ${again.message}`);
|
|
269
|
+
});
|
|
270
|
+
}
|
|
271
|
+
const { client, transport, resumed } = conn;
|
|
272
|
+
const sessionId = transport.sessionId;
|
|
273
|
+
if (!sessionId) {
|
|
274
|
+
await client.close().catch(() => { });
|
|
275
|
+
throw new BackgroundError(`the background server of "${id}" gave no session id`);
|
|
276
|
+
}
|
|
277
|
+
return {
|
|
278
|
+
id: sessionId,
|
|
279
|
+
get protocolVersion() {
|
|
280
|
+
return transport.protocolVersion;
|
|
281
|
+
},
|
|
282
|
+
resumed,
|
|
283
|
+
state,
|
|
284
|
+
async listTools() {
|
|
285
|
+
return (await client.listTools()).tools;
|
|
286
|
+
},
|
|
287
|
+
async callTool(name, args = {}, call = {}) {
|
|
288
|
+
return (await client.callTool({ name, arguments: args }, undefined, {
|
|
289
|
+
timeout: call.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS,
|
|
290
|
+
resetTimeoutOnProgress: true,
|
|
291
|
+
...(call.signal ? { signal: call.signal } : {}),
|
|
292
|
+
}));
|
|
293
|
+
},
|
|
294
|
+
async end() {
|
|
295
|
+
await transport.terminateSession().catch(() => { });
|
|
296
|
+
await client.close().catch(() => { });
|
|
297
|
+
},
|
|
298
|
+
async close() {
|
|
299
|
+
await client.close().catch(() => { });
|
|
300
|
+
},
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
//# sourceMappingURL=client.js.map
|
package/dist/diagnose.d.ts
CHANGED
|
@@ -30,6 +30,13 @@ export type Diagnosis = {
|
|
|
30
30
|
export declare function isActionabilityFailure(text: string): boolean;
|
|
31
31
|
/** The agent-facing message for a diagnosed failure. */
|
|
32
32
|
export declare function failureMessage(tool: string, target: string, d: Diagnosis | undefined, original: string): string;
|
|
33
|
+
/**
|
|
34
|
+
* Before a diagnosed call: when its target is in view and another element covers it, now and
|
|
35
|
+
* `COVER_STABLE_MS` later, the error that names that element; undefined (run the call) otherwise.
|
|
36
|
+
* Anything this check cannot tell (a target not found yet, out of view, in a frame) is left to
|
|
37
|
+
* Playwright and the diagnosis after it.
|
|
38
|
+
*/
|
|
39
|
+
export declare function coveredBeforeCall(page: Page | undefined, tool: string, args: Record<string, unknown>, json: boolean, wait?: (ms: number) => Promise<void>): Promise<ToolResult | undefined>;
|
|
33
40
|
/**
|
|
34
41
|
* Rewrites the error of a failed stock call when it is an actionability failure of a diagnosed
|
|
35
42
|
* tool; returns the result as it was otherwise.
|
package/dist/diagnose.js
CHANGED
|
@@ -2,9 +2,14 @@
|
|
|
2
2
|
* Click and type errors that say what is in the way. When an action on an element
|
|
3
3
|
* fails because the element cannot take it, Playwright retries until the action timeout and
|
|
4
4
|
* then reports "Timeout 5000ms exceeded" with a call log, which leaves the agent guessing. The
|
|
5
|
-
* host looks at the target once, after the failure
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* host looks at the target once, after the failure, and replaces the error with one that names
|
|
6
|
+
* the element in the way, or the state of the target, and the next step.
|
|
7
|
+
*
|
|
8
|
+
* One case is checked before the call too (`coveredBeforeCall`): a target in view that another
|
|
9
|
+
* element covers, such as a cookie banner over the page. When the same element still covers it
|
|
10
|
+
* a moment later, the call does not run and the agent hears which element is in the way at
|
|
11
|
+
* once, instead of after the 5 second action timeout. That check costs one look at the target
|
|
12
|
+
* per call and never scrolls the page.
|
|
8
13
|
*/
|
|
9
14
|
/** The stock tools whose failures are diagnosed, with the verb for the message. */
|
|
10
15
|
const DIAGNOSED_TOOLS = Object.freeze({
|
|
@@ -24,7 +29,7 @@ export function isActionabilityFailure(text) {
|
|
|
24
29
|
* Runs in the page, on the target element: what keeps an action from it. Self-contained, as
|
|
25
30
|
* Playwright serializes it.
|
|
26
31
|
*/
|
|
27
|
-
function inspect(el) {
|
|
32
|
+
function inspect(el, scroll = true) {
|
|
28
33
|
const clean = (s, max = 60) => {
|
|
29
34
|
const t = (s ?? "").replace(/\s+/g, " ").trim();
|
|
30
35
|
return t.length > max ? `${t.slice(0, max - 3)}...` : t;
|
|
@@ -130,10 +135,14 @@ function inspect(el) {
|
|
|
130
135
|
}
|
|
131
136
|
if ((el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) && el.readOnly)
|
|
132
137
|
return { state: "readonly", target };
|
|
133
|
-
|
|
138
|
+
if (scroll)
|
|
139
|
+
el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
|
|
134
140
|
const r = el.getBoundingClientRect();
|
|
135
141
|
const x = r.left + r.width / 2;
|
|
136
142
|
const y = r.top + r.height / 2;
|
|
143
|
+
// Without scrolling, a center outside the viewport cannot be hit-tested: nothing to say yet.
|
|
144
|
+
if (!scroll && (x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight))
|
|
145
|
+
return { state: "ok", target };
|
|
137
146
|
let hit = document.elementFromPoint(x, y);
|
|
138
147
|
while (hit?.shadowRoot) {
|
|
139
148
|
const inner = hit.shadowRoot.elementFromPoint(x, y);
|
|
@@ -187,7 +196,7 @@ function named(e) {
|
|
|
187
196
|
export function failureMessage(tool, target, d, original) {
|
|
188
197
|
const verb = DIAGNOSED_TOOLS[tool] ?? "act on";
|
|
189
198
|
const first = original.split("\n").find((l) => l.trim()) ?? original;
|
|
190
|
-
const detail = `Playwright: ${first.trim()}`;
|
|
199
|
+
const detail = original.startsWith("the call did not run") ? `turno: ${first.trim()}` : `Playwright: ${first.trim()}`;
|
|
191
200
|
if (!d) {
|
|
192
201
|
return [
|
|
193
202
|
`Could not ${verb} ${target}: the element is no longer on the page.`,
|
|
@@ -231,6 +240,52 @@ export function failureMessage(tool, target, d, original) {
|
|
|
231
240
|
].join("\n");
|
|
232
241
|
}
|
|
233
242
|
}
|
|
243
|
+
/** How long a cover must stay before the call is refused: an overlay fading out is let through. */
|
|
244
|
+
const COVER_STABLE_MS = 300;
|
|
245
|
+
/** The error result of a stock call, in the shape the call asked for. */
|
|
246
|
+
function errorOf(message, json) {
|
|
247
|
+
return {
|
|
248
|
+
isError: true,
|
|
249
|
+
content: [
|
|
250
|
+
{
|
|
251
|
+
type: "text",
|
|
252
|
+
text: json ? JSON.stringify({ isError: true, error: message }, null, 2) : `### Error\n${message}`,
|
|
253
|
+
},
|
|
254
|
+
],
|
|
255
|
+
};
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* Before a diagnosed call: when its target is in view and another element covers it, now and
|
|
259
|
+
* `COVER_STABLE_MS` later, the error that names that element; undefined (run the call) otherwise.
|
|
260
|
+
* Anything this check cannot tell (a target not found yet, out of view, in a frame) is left to
|
|
261
|
+
* Playwright and the diagnosis after it.
|
|
262
|
+
*/
|
|
263
|
+
export async function coveredBeforeCall(page, tool, args, json, wait = (ms) => new Promise((r) => setTimeout(r, ms))) {
|
|
264
|
+
if (!page || !(tool in DIAGNOSED_TOOLS))
|
|
265
|
+
return undefined;
|
|
266
|
+
const target = String(args.target ?? args.startTarget ?? "");
|
|
267
|
+
if (!target)
|
|
268
|
+
return undefined;
|
|
269
|
+
const look = async () => {
|
|
270
|
+
try {
|
|
271
|
+
const locator = locatorOf(page, target);
|
|
272
|
+
if ((await locator.count()) !== 1)
|
|
273
|
+
return undefined;
|
|
274
|
+
return await locator.evaluate(inspect, false, { timeout: 500 });
|
|
275
|
+
}
|
|
276
|
+
catch {
|
|
277
|
+
return undefined;
|
|
278
|
+
}
|
|
279
|
+
};
|
|
280
|
+
const first = await look();
|
|
281
|
+
if (first?.state !== "covered")
|
|
282
|
+
return undefined;
|
|
283
|
+
await wait(COVER_STABLE_MS);
|
|
284
|
+
const again = await look();
|
|
285
|
+
if (again?.state !== "covered" || again.cover.selector !== first.cover.selector)
|
|
286
|
+
return undefined;
|
|
287
|
+
return errorOf(failureMessage(tool, target, again, "the call did not run: the target is covered"), json);
|
|
288
|
+
}
|
|
234
289
|
/**
|
|
235
290
|
* Rewrites the error of a failed stock call when it is an actionability failure of a diagnosed
|
|
236
291
|
* tool; returns the result as it was otherwise.
|
package/dist/doctor.d.ts
CHANGED
|
@@ -1,17 +1,26 @@
|
|
|
1
|
+
import { type ProcTable } from "turno-core/process";
|
|
2
|
+
import { type SecretStore } from "turno-core/secrets";
|
|
3
|
+
import { type LightpandaInfo } from "./engine-lightpanda.js";
|
|
4
|
+
import { type CamoufoxInfo, type PlaywrightCoreInfo } from "./engine-camoufox.js";
|
|
1
5
|
/**
|
|
2
6
|
* `turno browser doctor`: what a browser identity needs to work, one check per row,
|
|
3
7
|
* each problem with the command that fixes it, like `turno doctor`.
|
|
4
8
|
*
|
|
5
9
|
* - Chrome: found, its version, and a smoke launch on a throwaway profile (headless).
|
|
6
10
|
* - System: a headed Chrome needs the desktop session (macOS) or a display (Linux).
|
|
11
|
+
* - Engines: Lightpanda for read mode and Camoufox with the stock Playwright it runs on (both
|
|
12
|
+
* optional; a failure only when an identity uses them), and a Lightpanda an earlier server
|
|
13
|
+
* left running.
|
|
7
14
|
* - Per identity: identity.json, who holds it (runtime lock and Chrome's profile lock), session
|
|
8
|
-
* health,
|
|
15
|
+
* health, challenges in the last 7 days, and the opt-in network settings (`proxy`: whether
|
|
16
|
+
* the secret store has its credentials, never their value; `userAgent`).
|
|
9
17
|
*
|
|
10
18
|
* `--fix` removes runtime locks whose process is gone and stops a Chrome an earlier run left
|
|
11
|
-
* behind on an identity's profile (the same sweep a server start does)
|
|
19
|
+
* behind on an identity's profile (the same sweep a server start does), and stops a Lightpanda
|
|
20
|
+
* an earlier server left running.
|
|
12
21
|
*/
|
|
13
22
|
export interface DoctorCheck {
|
|
14
|
-
/** "chrome", "system", "identities" or "identity <id>". */
|
|
23
|
+
/** "chrome", "system", "engines", "identities" or "identity <id>". */
|
|
15
24
|
area: string;
|
|
16
25
|
level: "ok" | "warn" | "fail" | "info";
|
|
17
26
|
text: string;
|
|
@@ -37,8 +46,33 @@ export interface DoctorOptions {
|
|
|
37
46
|
chrome?: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform) => ChromeInfo | undefined;
|
|
38
47
|
/** Starts and closes Chrome on a temporary profile; resolves with the milliseconds it took. */
|
|
39
48
|
smoke?: (env: NodeJS.ProcessEnv) => Promise<number>;
|
|
49
|
+
/** Finds Lightpanda (tests inject one). */
|
|
50
|
+
lightpanda?: (env: NodeJS.ProcessEnv) => LightpandaInfo | undefined;
|
|
51
|
+
/** Finds Camoufox and the stock Playwright it runs on (tests inject them). */
|
|
52
|
+
camoufox?: (env: NodeJS.ProcessEnv) => CamoufoxInfo | undefined;
|
|
53
|
+
playwrightCore?: (env: NodeJS.ProcessEnv) => (PlaywrightCoreInfo & {
|
|
54
|
+
ok: boolean;
|
|
55
|
+
}) | undefined;
|
|
56
|
+
/** The secret store proxy credentials come from (tests inject a fake); default: this machine's. */
|
|
57
|
+
secrets?: SecretStore;
|
|
58
|
+
/** The process table, for a Lightpanda left running (tests inject one). */
|
|
59
|
+
procTable?: () => ProcTable | undefined;
|
|
60
|
+
/** The mcp.toml servers that run turno-browser-mcp for an identity (turno-cli reads mcp.toml). */
|
|
61
|
+
servers?: readonly ServedIdentity[];
|
|
40
62
|
now?: Date;
|
|
41
63
|
}
|
|
64
|
+
/** One mcp.toml server of an identity, as mcpd runs it. */
|
|
65
|
+
export interface ServedIdentity {
|
|
66
|
+
/** The server's name in mcp.toml (`browser-work`). */
|
|
67
|
+
name: string;
|
|
68
|
+
identity: string;
|
|
69
|
+
/** mcp.toml `exclusive`: one client session at a time. */
|
|
70
|
+
exclusive: boolean;
|
|
71
|
+
/** mcp.toml `scope`: with "session" every client session gets its own server. */
|
|
72
|
+
scope: string;
|
|
73
|
+
/** A `--sharing` flag in the server's args, which wins over identity.json. */
|
|
74
|
+
sharing?: string;
|
|
75
|
+
}
|
|
42
76
|
export interface DoctorReport {
|
|
43
77
|
checks: DoctorCheck[];
|
|
44
78
|
/** What `--fix` did. */
|