turno-browser 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +32 -3
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +116 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +599 -0
  7. package/dist/api.d.ts +29 -2
  8. package/dist/api.js +29 -2
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/batch.d.ts +5 -0
  12. package/dist/batch.js +3 -3
  13. package/dist/bin/mcp.js +58 -1
  14. package/dist/captcha.d.ts +77 -0
  15. package/dist/captcha.js +333 -0
  16. package/dist/cdp-relay.d.ts +20 -0
  17. package/dist/cdp-relay.js +101 -0
  18. package/dist/chrome-features.d.ts +23 -0
  19. package/dist/chrome-features.js +44 -0
  20. package/dist/diagnose.d.ts +7 -0
  21. package/dist/diagnose.js +61 -6
  22. package/dist/doctor.d.ts +37 -3
  23. package/dist/doctor.js +230 -5
  24. package/dist/engine-attach.d.ts +27 -0
  25. package/dist/engine-attach.js +165 -0
  26. package/dist/engine-camoufox.d.ts +32 -0
  27. package/dist/engine-camoufox.js +270 -0
  28. package/dist/engine-lightpanda.d.ts +72 -0
  29. package/dist/engine-lightpanda.js +292 -0
  30. package/dist/engine.d.ts +63 -11
  31. package/dist/engine.js +104 -28
  32. package/dist/flows.d.ts +127 -0
  33. package/dist/flows.js +294 -0
  34. package/dist/governor.d.ts +42 -7
  35. package/dist/governor.js +82 -32
  36. package/dist/host.d.ts +17 -2
  37. package/dist/host.js +618 -41
  38. package/dist/human-input.d.ts +84 -0
  39. package/dist/human-input.js +443 -0
  40. package/dist/humanize.d.ts +123 -0
  41. package/dist/humanize.js +241 -0
  42. package/dist/identities.js +2 -0
  43. package/dist/idle-timer.d.ts +12 -0
  44. package/dist/idle-timer.js +25 -0
  45. package/dist/index.d.ts +8 -3
  46. package/dist/index.js +5 -1
  47. package/dist/lifecycle.d.ts +9 -1
  48. package/dist/lifecycle.js +9 -1
  49. package/dist/live-client.d.ts +22 -0
  50. package/dist/live-client.js +93 -0
  51. package/dist/live-page.d.ts +11 -0
  52. package/dist/live-page.js +143 -0
  53. package/dist/live-server.d.ts +173 -0
  54. package/dist/live-server.js +640 -0
  55. package/dist/live.d.ts +120 -0
  56. package/dist/live.js +203 -0
  57. package/dist/login-tool.d.ts +13 -0
  58. package/dist/login-tool.js +5 -1
  59. package/dist/login.d.ts +4 -1
  60. package/dist/login.js +11 -2
  61. package/dist/network-chrome.d.ts +74 -0
  62. package/dist/network-chrome.js +178 -0
  63. package/dist/network.d.ts +125 -0
  64. package/dist/network.js +263 -0
  65. package/dist/opt-in-settings.d.ts +69 -0
  66. package/dist/opt-in-settings.js +151 -0
  67. package/dist/recorder.d.ts +88 -0
  68. package/dist/recorder.js +538 -0
  69. package/dist/recordings.d.ts +116 -0
  70. package/dist/recordings.js +474 -0
  71. package/dist/redact.d.ts +7 -0
  72. package/dist/redact.js +18 -0
  73. package/dist/replay.d.ts +20 -0
  74. package/dist/replay.js +382 -0
  75. package/dist/reputation.d.ts +24 -2
  76. package/dist/reputation.js +63 -17
  77. package/dist/session-export.js +1 -1
  78. package/dist/session.d.ts +10 -2
  79. package/dist/session.js +10 -2
  80. package/dist/settings.d.ts +104 -2
  81. package/dist/settings.js +204 -6
  82. package/dist/sharing.d.ts +96 -0
  83. package/dist/sharing.js +269 -0
  84. package/dist/snippet.d.ts +8 -2
  85. package/dist/snippet.js +10 -4
  86. package/dist/tab-locks.d.ts +63 -0
  87. package/dist/tab-locks.js +179 -0
  88. package/dist/tools.d.ts +38 -0
  89. package/dist/tools.js +20 -1
  90. package/dist/tuning.d.ts +14 -0
  91. package/dist/tuning.js +9 -0
  92. package/dist/upstream.d.ts +11 -0
  93. package/npm-shrinkwrap.json +2 -2
  94. package/package.json +1 -1
@@ -0,0 +1,333 @@
1
+ import { secretStore } from "turno-core/secrets";
2
+ import { captchaTimeoutMs } from "./opt-in-settings.js";
3
+ import { recordSolve } from "./reputation.js";
4
+ import { readIdentitySettings } from "./settings.js";
5
+ import { upstream } from "./upstream.js";
6
+ /**
7
+ * Captcha solving, off by default (identity.json `captcha`). `browser_solve_captcha` finds a
8
+ * captcha widget on the current tab, sends its kind, site key and the page URL to the solver
9
+ * service the person configured, and puts the token it returns into the page's response field
10
+ * (and the widget's callback, when it names one). The agent then submits the form itself.
11
+ *
12
+ * What it is and is not:
13
+ *
14
+ * - The solver is a third party: it sees the page URL and the widget, and usually loads the
15
+ * page on its own machines to answer. Its key comes from the secret store through a
16
+ * `keychain:` reference, joins the redactor, and never appears in a tool argument or result.
17
+ * - It answers only the widgets that hand back a token (`WIDGETS`). A full-page "checking your
18
+ * browser" interstitial, a "verify it's you" prompt or a block page is left to the person.
19
+ * - Every attempt, solved or not, is one line in the identity's reputation log (`reputation.ts`)
20
+ * with the host name, the widget kind and the provider: never the token or the key.
21
+ * - Many sites' terms forbid solving their captchas by machine; the docs say so and say it is
22
+ * meant for the person's own accounts.
23
+ */
24
+ /** The widgets a token answers, with the task type of the task protocol and where the token goes. */
25
+ export const WIDGETS = {
26
+ recaptcha: { task: "RecaptchaV2TaskProxyless", fields: ["g-recaptcha-response"], label: "reCAPTCHA v2" },
27
+ hcaptcha: {
28
+ task: "HCaptchaTaskProxyless",
29
+ fields: ["h-captcha-response", "g-recaptcha-response"],
30
+ label: "hCaptcha",
31
+ },
32
+ turnstile: { task: "TurnstileTaskProxyless", fields: ["cf-turnstile-response"], label: "Turnstile" },
33
+ };
34
+ class SolverError extends Error {
35
+ constructor(message) {
36
+ super(message);
37
+ this.name = "SolverError";
38
+ }
39
+ }
40
+ /**
41
+ * The task protocol many solver services share: `POST <endpoint>/createTask` with the account
42
+ * key and a task, then `POST <endpoint>/getTaskResult` until the task is ready. Errors come back
43
+ * as `errorId` with `errorCode` and `errorDescription`.
44
+ */
45
+ export function taskApiSolver(options) {
46
+ const base = options.endpoint.replace(/\/+$/, "");
47
+ const host = new URL(options.endpoint).host;
48
+ const doFetch = options.fetch ?? fetch;
49
+ const polls = options.polls?.length ? options.polls : [1_000, 2_000, 3_000];
50
+ const post = async (path, body, signal) => {
51
+ let res;
52
+ try {
53
+ res = await doFetch(`${base}/${path}`, {
54
+ method: "POST",
55
+ headers: { "content-type": "application/json" },
56
+ body: JSON.stringify({ clientKey: options.key, ...body }),
57
+ ...(signal ? { signal } : {}),
58
+ });
59
+ }
60
+ catch (error) {
61
+ if (signal?.aborted)
62
+ throw new SolverError("the solver did not answer in time");
63
+ throw new SolverError(`cannot reach ${host}: ${error.message}`);
64
+ }
65
+ const text = await res.text().catch(() => "");
66
+ if (!res.ok)
67
+ throw new SolverError(`${host} answered ${res.status}`);
68
+ let json;
69
+ try {
70
+ json = JSON.parse(text);
71
+ }
72
+ catch {
73
+ throw new SolverError(`${host} did not answer with JSON`);
74
+ }
75
+ if (json.errorId !== undefined && json.errorId !== 0) {
76
+ const code = typeof json.errorCode === "string" ? json.errorCode : `error ${String(json.errorId)}`;
77
+ const why = typeof json.errorDescription === "string" ? `: ${json.errorDescription.slice(0, 200)}` : "";
78
+ throw new SolverError(`${host} refused the task (${code}${why})`);
79
+ }
80
+ return json;
81
+ };
82
+ return {
83
+ label: `task-api at ${host}`,
84
+ provider: "task-api",
85
+ async solve({ widget, pageUrl, signal }) {
86
+ const created = await post("createTask", {
87
+ task: {
88
+ type: WIDGETS[widget.kind].task,
89
+ websiteURL: pageUrl,
90
+ websiteKey: widget.siteKey,
91
+ ...(widget.invisible ? { isInvisible: true } : {}),
92
+ },
93
+ }, signal);
94
+ const taskId = created.taskId;
95
+ if (typeof taskId !== "string" && typeof taskId !== "number")
96
+ throw new SolverError(`${host} gave no task id`);
97
+ for (let i = 0;; i++) {
98
+ const wait = polls[Math.min(i, polls.length - 1)];
99
+ await new Promise((resolve, reject) => {
100
+ if (signal?.aborted) {
101
+ reject(new SolverError("the solver did not answer in time"));
102
+ return;
103
+ }
104
+ const t = setTimeout(resolve, wait);
105
+ signal?.addEventListener("abort", () => {
106
+ clearTimeout(t);
107
+ reject(new SolverError("the solver did not answer in time"));
108
+ }, { once: true });
109
+ });
110
+ const result = await post("getTaskResult", { taskId }, signal);
111
+ if (result.status === "processing")
112
+ continue;
113
+ const solution = result.solution;
114
+ const token = solution?.gRecaptchaResponse ?? solution?.token;
115
+ if (result.status === "ready" && typeof token === "string" && token)
116
+ return { token };
117
+ throw new SolverError(`${host} answered without a token`);
118
+ }
119
+ },
120
+ };
121
+ }
122
+ /** The captcha widgets of a page's main frame, first the ones its markup declares. */
123
+ async function findWidgets(page) {
124
+ return await page
125
+ .evaluate(() => {
126
+ const found = [];
127
+ const declared = [
128
+ ["recaptcha", ".g-recaptcha[data-sitekey]"],
129
+ ["hcaptcha", ".h-captcha[data-sitekey]"],
130
+ ["turnstile", ".cf-turnstile[data-sitekey]"],
131
+ ];
132
+ for (const [kind, selector] of declared) {
133
+ for (const el of Array.from(document.querySelectorAll(selector))) {
134
+ const siteKey = el.getAttribute("data-sitekey") ?? "";
135
+ const callback = el.getAttribute("data-callback") ?? undefined;
136
+ found.push({
137
+ kind,
138
+ siteKey,
139
+ ...(el.getAttribute("data-size") === "invisible" ? { invisible: true } : {}),
140
+ ...(callback ? { callback } : {}),
141
+ });
142
+ }
143
+ }
144
+ // A widget rendered from script has no declaring element: its frame's URL carries the key.
145
+ for (const frame of Array.from(document.querySelectorAll("iframe[src]"))) {
146
+ let url;
147
+ try {
148
+ url = new URL(frame.src);
149
+ }
150
+ catch {
151
+ continue;
152
+ }
153
+ const add = (kind, siteKey, invisible) => {
154
+ if (siteKey && !found.some((f) => f.kind === kind && f.siteKey === siteKey))
155
+ found.push({ kind, siteKey, ...(invisible ? { invisible } : {}) });
156
+ };
157
+ if (/\/recaptcha\/(api2|enterprise)\/anchor/.test(url.pathname))
158
+ add("recaptcha", url.searchParams.get("k"), url.searchParams.get("size") === "invisible");
159
+ else if (/hcaptcha/.test(url.hostname))
160
+ add("hcaptcha", url.searchParams.get("sitekey") ?? new URLSearchParams(url.hash.slice(1)).get("sitekey"));
161
+ else if (url.hostname === "challenges.cloudflare.com")
162
+ add("turnstile", /\/(0x[0-9A-Za-z_-]{10,})\//.exec(url.pathname)?.[1]);
163
+ }
164
+ return found.filter((f) => f.siteKey);
165
+ })
166
+ .then((list) => list)
167
+ .catch(() => []);
168
+ }
169
+ /**
170
+ * Puts a token where the widget's form reads it, and calls the widget's callback. The fields
171
+ * are set from Patchright's isolated world, like every other turno script; the callback is a
172
+ * function of the page's own scripts, so only that call runs in the page's main world.
173
+ */
174
+ async function applyToken(page, widget, token) {
175
+ const fields = await page.evaluate(({ names, token }) => {
176
+ let set = 0;
177
+ for (const name of names) {
178
+ for (const el of Array.from(document.querySelectorAll(`[name="${name}"], #${name}`))) {
179
+ el.value = token;
180
+ set++;
181
+ }
182
+ }
183
+ return set;
184
+ }, { names: [...WIDGETS[widget.kind].fields], token });
185
+ let callback = false;
186
+ if (widget.callback && /^[A-Za-z_$][\w$.]*$/.test(widget.callback)) {
187
+ callback = await page
188
+ .evaluate(({ path, token }) => {
189
+ let fn = window;
190
+ for (const part of path.split("."))
191
+ fn = fn?.[part];
192
+ if (typeof fn !== "function")
193
+ return false;
194
+ fn(token);
195
+ return true;
196
+ }, { path: widget.callback, token }, undefined, false)
197
+ .catch(() => false);
198
+ }
199
+ return { fields, callback };
200
+ }
201
+ /** The configured solver, its key from the secret store; the key joins the redactor first. */
202
+ async function resolveSolver(ctx, settings) {
203
+ const vault = ctx.vault;
204
+ const item = settings.key.slice("keychain:".length);
205
+ const store = vault.store ?? secretStore(vault.identity.env);
206
+ if (!store)
207
+ throw new SolverError(`captcha.key names ${settings.key}, but this machine has no secret store`);
208
+ const key = await store.get(item).catch(() => undefined);
209
+ if (key === undefined)
210
+ throw new SolverError(`the secret store has no item "${item}" for captcha.key (store it with: turno secret set ${item})`);
211
+ vault.redactor.add(key, "captcha solver key");
212
+ return taskApiSolver({
213
+ endpoint: settings.endpoint,
214
+ key,
215
+ ...(ctx.providers?.fetch ? { fetch: ctx.providers.fetch } : {}),
216
+ });
217
+ }
218
+ function fail(message) {
219
+ return { content: [{ type: "text", text: `### Error\n${message}` }], isError: true };
220
+ }
221
+ function solveSchema() {
222
+ const z = upstream().utils.z;
223
+ return {
224
+ name: "browser_solve_captcha",
225
+ title: "Solve the captcha on the page",
226
+ description: [
227
+ "Solve the captcha widget on the current tab (reCAPTCHA v2, hCaptcha or Turnstile) through the solver service the person configured for this browser identity, and put the token into the page.",
228
+ "Call it only when a captcha stands between you and a step the person asked for on their own account; then submit the form yourself, before the token expires (about two minutes).",
229
+ "It does not answer full-page browser checks, verify-it's-you prompts or block pages: hand those to the person.",
230
+ "The solver sees the page URL and the widget. Every use is logged in the identity's reputation log.",
231
+ ].join(" "),
232
+ inputSchema: z.object({}),
233
+ type: "action",
234
+ };
235
+ }
236
+ export function solveCaptchaTool() {
237
+ let schema;
238
+ return {
239
+ get schema() {
240
+ schema ??= solveSchema();
241
+ return schema;
242
+ },
243
+ async handle(ctx) {
244
+ const vault = ctx.vault;
245
+ const page = ctx.stock?.currentPage();
246
+ if (!vault || !ctx.stock)
247
+ return fail("browser_solve_captcha needs a browser identity (turno-browser-mcp --identity <id>)");
248
+ const { identity } = vault;
249
+ let settings;
250
+ try {
251
+ settings = readIdentitySettings(identity.id, identity.env)?.captcha;
252
+ }
253
+ catch (error) {
254
+ return fail(error.message);
255
+ }
256
+ if (!settings)
257
+ return fail(`captcha solving is off for identity "${identity.id}"; only the person can turn it on (turno identity set browser:${identity.id} --captcha-provider task-api --captcha-endpoint <url> --captcha-key keychain:<item>). Otherwise ask them to answer it in the browser window.`);
258
+ if (!page)
259
+ return fail("there is no page open: navigate to the page with the captcha first");
260
+ let url;
261
+ try {
262
+ url = new URL(page.url());
263
+ }
264
+ catch {
265
+ return fail("the current page has no web address");
266
+ }
267
+ if (url.protocol !== "https:" && url.protocol !== "http:")
268
+ return fail("the current page is not a web page");
269
+ const widgets = await findWidgets(page);
270
+ const widget = widgets[0];
271
+ if (!widget)
272
+ return fail("no captcha widget this tool can answer is on the current page (reCAPTCHA v2, hCaptcha, Turnstile). A full-page browser check, a verify-it's-you prompt or a block page is for the person to handle in the window.");
273
+ const timeoutMs = captchaTimeoutMs(settings);
274
+ const controller = new AbortController();
275
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
276
+ timer.unref?.();
277
+ const onAbort = () => controller.abort();
278
+ ctx.signal?.addEventListener("abort", onAbort, { once: true });
279
+ const started = Date.now();
280
+ const log = (ok) => {
281
+ try {
282
+ recordSolve(identity.id, identity.env, {
283
+ site: url.hostname,
284
+ widget: widget.kind,
285
+ provider: settings.provider,
286
+ ok,
287
+ });
288
+ }
289
+ catch {
290
+ /* the log is best effort; a full disk must not break a tool call */
291
+ }
292
+ };
293
+ try {
294
+ const solver = ctx.providers?.solver ?? (await resolveSolver(ctx, settings));
295
+ const { token } = await solver.solve({ widget, pageUrl: page.url(), signal: controller.signal });
296
+ const applied = await applyToken(page, widget, token);
297
+ log(true);
298
+ const seconds = ((Date.now() - started) / 1000).toFixed(1);
299
+ const placed = applied.fields || applied.callback
300
+ ? `Token put into the page${applied.fields ? ` (${applied.fields} response field${applied.fields === 1 ? "" : "s"})` : ""}${applied.callback ? `; the widget's callback ${widget.callback} ran` : ""}.`
301
+ : "The page has no response field or callback for the token yet; its widget script may not have loaded. Try again after it shows.";
302
+ return {
303
+ content: [
304
+ {
305
+ type: "text",
306
+ text: [
307
+ "### Captcha",
308
+ `Widget: ${WIDGETS[widget.kind].label}${widgets.length > 1 ? ` (the first of ${widgets.length} on the page)` : ""}`,
309
+ `Solver: ${solver.label}, ${seconds} s`,
310
+ placed,
311
+ `Logged in the reputation log of "${identity.id}".`,
312
+ "Next: submit the form now; the token expires in about two minutes.",
313
+ ].join("\n"),
314
+ },
315
+ ],
316
+ ...(applied.fields || applied.callback ? {} : { isError: true }),
317
+ };
318
+ }
319
+ catch (error) {
320
+ log(false);
321
+ const why = controller.signal.aborted
322
+ ? `the solver did not answer within ${timeoutMs / 1000} s`
323
+ : error.message;
324
+ return fail(`the captcha was not solved: ${why}. Ask the person to answer it in the browser window.`);
325
+ }
326
+ finally {
327
+ clearTimeout(timer);
328
+ ctx.signal?.removeEventListener("abort", onAbort);
329
+ }
330
+ },
331
+ };
332
+ }
333
+ //# sourceMappingURL=captcha.js.map
@@ -0,0 +1,20 @@
1
+ interface Message {
2
+ id?: number;
3
+ sessionId?: string;
4
+ method?: string;
5
+ result?: Record<string, unknown>;
6
+ error?: unknown;
7
+ }
8
+ /**
9
+ * The reply to send instead of `reply`, or undefined to pass it through. A reply Patchright would
10
+ * choke on becomes a protocol error, which it handles (`_sendMayFail` returns nothing).
11
+ */
12
+ export declare function fixReply(method: string | undefined, reply: Message): Message | undefined;
13
+ export interface CdpRelay {
14
+ /** What Patchright connects to: `ws+unix://<socket>:/`. */
15
+ endpoint: string;
16
+ close(): Promise<void>;
17
+ }
18
+ /** Relays `listenPath` to the CDP server on `targetPath` (both Unix sockets). */
19
+ export declare function startCdpRelay(listenPath: string, targetPath: string): Promise<CdpRelay>;
20
+ export {};
@@ -0,0 +1,101 @@
1
+ import { createServer } from "node:http";
2
+ import { upstream } from "./upstream.js";
3
+ const OPEN = 1;
4
+ /**
5
+ * The reply to send instead of `reply`, or undefined to pass it through. A reply Patchright would
6
+ * choke on becomes a protocol error, which it handles (`_sendMayFail` returns nothing).
7
+ */
8
+ export function fixReply(method, reply) {
9
+ if (method === "DOM.getDocument" && reply.result && !reply.result.root) {
10
+ return {
11
+ id: reply.id,
12
+ ...(reply.sessionId ? { sessionId: reply.sessionId } : {}),
13
+ error: { code: -32000, message: "No document on this target" },
14
+ };
15
+ }
16
+ return undefined;
17
+ }
18
+ /** Relays `listenPath` to the CDP server on `targetPath` (both Unix sockets). */
19
+ export async function startCdpRelay(listenPath, targetPath) {
20
+ const { ws: WebSocket, wsServer: WebSocketServer } = upstream().utils;
21
+ const wss = new WebSocketServer({ noServer: true, maxPayload: 256 * 1024 * 1024 });
22
+ const live = new Set();
23
+ const server = createServer((_req, res) => {
24
+ res.writeHead(404).end();
25
+ });
26
+ server.on("upgrade", (request, socket, head) => {
27
+ wss.handleUpgrade(request, socket, head, (client) => {
28
+ const target = new WebSocket(`ws+unix://${targetPath}:/`, { maxPayload: 256 * 1024 * 1024 });
29
+ live.add(client);
30
+ live.add(target);
31
+ const queue = [];
32
+ // The method of each request in flight, by session and id, to know what a reply answers.
33
+ const methods = new Map();
34
+ target.on("open", () => {
35
+ for (const m of queue.splice(0))
36
+ target.send(m);
37
+ });
38
+ client.on("message", (data) => {
39
+ const text = data.toString();
40
+ try {
41
+ const m = JSON.parse(text);
42
+ if (m.id !== undefined && m.method)
43
+ methods.set(`${m.sessionId ?? ""}:${m.id}`, m.method);
44
+ }
45
+ catch {
46
+ /* not JSON: pass it on and let the browser answer */
47
+ }
48
+ if (target.readyState === OPEN)
49
+ target.send(text);
50
+ else
51
+ queue.push(text);
52
+ });
53
+ target.on("message", (data) => {
54
+ let text = data.toString();
55
+ try {
56
+ const m = JSON.parse(text);
57
+ if (m.id !== undefined) {
58
+ const key = `${m.sessionId ?? ""}:${m.id}`;
59
+ const fixed = fixReply(methods.get(key), m);
60
+ methods.delete(key);
61
+ if (fixed)
62
+ text = JSON.stringify(fixed);
63
+ }
64
+ }
65
+ catch {
66
+ /* pass it through */
67
+ }
68
+ if (client.readyState === OPEN)
69
+ client.send(text);
70
+ });
71
+ const end = () => {
72
+ live.delete(client);
73
+ live.delete(target);
74
+ client.close();
75
+ target.close();
76
+ };
77
+ client.on("close", end);
78
+ target.on("close", end);
79
+ client.on("error", end);
80
+ target.on("error", end);
81
+ });
82
+ });
83
+ await new Promise((resolve, reject) => {
84
+ server.once("error", reject);
85
+ server.listen(listenPath, () => {
86
+ server.off("error", reject);
87
+ resolve();
88
+ });
89
+ });
90
+ return {
91
+ endpoint: `ws+unix://${listenPath}:/`,
92
+ async close() {
93
+ for (const socket of live)
94
+ socket.terminate();
95
+ live.clear();
96
+ wss.close();
97
+ await new Promise((resolve) => server.close(() => resolve()));
98
+ },
99
+ };
100
+ }
101
+ //# sourceMappingURL=cdp-relay.js.map
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Chrome features Playwright turns off, and the one turno turns back on.
3
+ *
4
+ * Playwright starts Chrome with one `--disable-features=` list (its `chromiumSwitches`). Among
5
+ * them is `ThirdPartyStoragePartitioning`, which every Chrome since 115 has on: a site embedded
6
+ * in another site gets its own storage there (localStorage, IndexedDB, caches) instead of its
7
+ * first-party storage. A page can tell the difference, and a person's Chrome never has it off,
8
+ * so turno's Chrome engine drops Playwright's list and passes the same list without that one
9
+ * feature. Chrome reads the last `--disable-features` it is given, so the list goes before the
10
+ * user's own launch args: a `--disable-features` there still wins, as it did before.
11
+ *
12
+ * The list is a copy of Playwright's: `test/chrome-features.test.ts` reads the installed
13
+ * patchright-core and fails when they drift apart after an update.
14
+ */
15
+ /** The feature turno leaves on. */
16
+ export declare const KEPT_FEATURE = "ThirdPartyStoragePartitioning";
17
+ /** Playwright's `disabledFeatures` (patchright-core 1.64), in its order. */
18
+ export declare const PLAYWRIGHT_DISABLED_FEATURES: readonly string[];
19
+ /** The switches for a Chrome turno launches: Playwright's list to drop, and the one to pass. */
20
+ export declare function storagePartitioningArgs(): {
21
+ ignoreDefaultArgs: string[];
22
+ args: string[];
23
+ };
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Chrome features Playwright turns off, and the one turno turns back on.
3
+ *
4
+ * Playwright starts Chrome with one `--disable-features=` list (its `chromiumSwitches`). Among
5
+ * them is `ThirdPartyStoragePartitioning`, which every Chrome since 115 has on: a site embedded
6
+ * in another site gets its own storage there (localStorage, IndexedDB, caches) instead of its
7
+ * first-party storage. A page can tell the difference, and a person's Chrome never has it off,
8
+ * so turno's Chrome engine drops Playwright's list and passes the same list without that one
9
+ * feature. Chrome reads the last `--disable-features` it is given, so the list goes before the
10
+ * user's own launch args: a `--disable-features` there still wins, as it did before.
11
+ *
12
+ * The list is a copy of Playwright's: `test/chrome-features.test.ts` reads the installed
13
+ * patchright-core and fails when they drift apart after an update.
14
+ */
15
+ /** The feature turno leaves on. */
16
+ export const KEPT_FEATURE = "ThirdPartyStoragePartitioning";
17
+ /** Playwright's `disabledFeatures` (patchright-core 1.64), in its order. */
18
+ export const PLAYWRIGHT_DISABLED_FEATURES = Object.freeze([
19
+ "AvoidUnnecessaryBeforeUnloadCheckSync",
20
+ "DestroyProfileOnBrowserClose",
21
+ "DialMediaRouteProvider",
22
+ "GlobalMediaControls",
23
+ "HttpsUpgrades",
24
+ "LensOverlay",
25
+ "PaintHolding",
26
+ "ThirdPartyStoragePartitioning",
27
+ "BlockOriginHeaderModificationOnRedirect",
28
+ "AvoidCorsURLLoaderRestartOnRedirect",
29
+ "Translate",
30
+ "AutoDeElevate",
31
+ "OptimizationHints",
32
+ "NetworkTimeServiceQuerying",
33
+ "AimEnabled",
34
+ "msForceBrowserSignIn",
35
+ "msEdgeUpdateLaunchServicesPreferredVersion",
36
+ ]);
37
+ /** The switches for a Chrome turno launches: Playwright's list to drop, and the one to pass. */
38
+ export function storagePartitioningArgs() {
39
+ return {
40
+ ignoreDefaultArgs: [`--disable-features=${PLAYWRIGHT_DISABLED_FEATURES.join(",")}`],
41
+ args: [`--disable-features=${PLAYWRIGHT_DISABLED_FEATURES.filter((f) => f !== KEPT_FEATURE).join(",")}`],
42
+ };
43
+ }
44
+ //# sourceMappingURL=chrome-features.js.map
@@ -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 (a successful call costs nothing), and
6
- * replaces the error with one that names the element in the way, or the state of the target,
7
- * and the next step.
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
- el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
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.