turno-browser 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +95 -123
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +117 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +600 -0
  7. package/dist/api.d.ts +90 -2
  8. package/dist/api.js +41 -4
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/background-state.d.ts +54 -0
  12. package/dist/background-state.js +97 -0
  13. package/dist/background.d.ts +69 -0
  14. package/dist/background.js +458 -0
  15. package/dist/batch.d.ts +5 -0
  16. package/dist/batch.js +3 -3
  17. package/dist/bin/mcp.js +103 -6
  18. package/dist/captcha.d.ts +77 -0
  19. package/dist/captcha.js +334 -0
  20. package/dist/cdp-relay.d.ts +20 -0
  21. package/dist/cdp-relay.js +101 -0
  22. package/dist/chrome-features.d.ts +23 -0
  23. package/dist/chrome-features.js +44 -0
  24. package/dist/cli/background.d.ts +11 -0
  25. package/dist/cli/background.js +132 -0
  26. package/dist/cli/commands.d.ts +16 -0
  27. package/dist/cli/commands.js +515 -0
  28. package/dist/cli/context.d.ts +75 -0
  29. package/dist/cli/context.js +44 -0
  30. package/dist/cli/do-background.d.ts +27 -0
  31. package/dist/cli/do-background.js +212 -0
  32. package/dist/cli/do.d.ts +85 -0
  33. package/dist/cli/do.js +558 -0
  34. package/dist/cli/flows.d.ts +28 -0
  35. package/dist/cli/flows.js +303 -0
  36. package/dist/cli/identity.d.ts +37 -0
  37. package/dist/cli/identity.js +906 -0
  38. package/dist/cli/live.d.ts +7 -0
  39. package/dist/cli/live.js +99 -0
  40. package/dist/cli/main.d.ts +16 -0
  41. package/dist/cli/main.js +171 -0
  42. package/dist/cli/secret.d.ts +4 -0
  43. package/dist/cli/secret.js +151 -0
  44. package/dist/cli/session.d.ts +6 -0
  45. package/dist/cli/session.js +106 -0
  46. package/dist/cli/setup.d.ts +7 -0
  47. package/dist/cli/setup.js +180 -0
  48. package/dist/cli/vault.d.ts +5 -0
  49. package/dist/cli/vault.js +192 -0
  50. package/dist/client.d.ts +82 -0
  51. package/dist/client.js +303 -0
  52. package/dist/diagnose.d.ts +7 -0
  53. package/dist/diagnose.js +61 -6
  54. package/dist/doctor.d.ts +37 -3
  55. package/dist/doctor.js +264 -6
  56. package/dist/engine-attach.d.ts +27 -0
  57. package/dist/engine-attach.js +165 -0
  58. package/dist/engine-camoufox.d.ts +32 -0
  59. package/dist/engine-camoufox.js +271 -0
  60. package/dist/engine-lightpanda.d.ts +72 -0
  61. package/dist/engine-lightpanda.js +293 -0
  62. package/dist/engine.d.ts +63 -11
  63. package/dist/engine.js +106 -29
  64. package/dist/flows.d.ts +127 -0
  65. package/dist/flows.js +294 -0
  66. package/dist/governor.d.ts +42 -7
  67. package/dist/governor.js +82 -32
  68. package/dist/health.js +2 -1
  69. package/dist/host.d.ts +38 -2
  70. package/dist/host.js +689 -52
  71. package/dist/human-input.d.ts +84 -0
  72. package/dist/human-input.js +448 -0
  73. package/dist/humanize.d.ts +123 -0
  74. package/dist/humanize.js +241 -0
  75. package/dist/identities.js +4 -1
  76. package/dist/idle-timer.d.ts +12 -0
  77. package/dist/idle-timer.js +25 -0
  78. package/dist/index.d.ts +13 -4
  79. package/dist/index.js +7 -1
  80. package/dist/lifecycle.d.ts +11 -1
  81. package/dist/lifecycle.js +11 -2
  82. package/dist/live-client.d.ts +22 -0
  83. package/dist/live-client.js +95 -0
  84. package/dist/live-page.d.ts +4 -0
  85. package/dist/live-page.js +144 -0
  86. package/dist/live-server.d.ts +173 -0
  87. package/dist/live-server.js +643 -0
  88. package/dist/live.d.ts +120 -0
  89. package/dist/live.js +204 -0
  90. package/dist/login-tool.d.ts +13 -0
  91. package/dist/login-tool.js +8 -3
  92. package/dist/login.d.ts +4 -1
  93. package/dist/login.js +12 -2
  94. package/dist/names.d.ts +28 -0
  95. package/dist/names.js +25 -0
  96. package/dist/network-chrome.d.ts +74 -0
  97. package/dist/network-chrome.js +178 -0
  98. package/dist/network.d.ts +125 -0
  99. package/dist/network.js +264 -0
  100. package/dist/opt-in-settings.d.ts +69 -0
  101. package/dist/opt-in-settings.js +152 -0
  102. package/dist/recorder.d.ts +88 -0
  103. package/dist/recorder.js +538 -0
  104. package/dist/recordings.d.ts +116 -0
  105. package/dist/recordings.js +474 -0
  106. package/dist/redact.d.ts +7 -0
  107. package/dist/redact.js +18 -0
  108. package/dist/replay.d.ts +20 -0
  109. package/dist/replay.js +383 -0
  110. package/dist/reputation.d.ts +24 -2
  111. package/dist/reputation.js +63 -17
  112. package/dist/runtime-lock.js +3 -2
  113. package/dist/session-export.js +1 -1
  114. package/dist/session.d.ts +10 -2
  115. package/dist/session.js +10 -2
  116. package/dist/settings.d.ts +104 -2
  117. package/dist/settings.js +204 -6
  118. package/dist/sharing.d.ts +96 -0
  119. package/dist/sharing.js +269 -0
  120. package/dist/snippet.d.ts +8 -2
  121. package/dist/snippet.js +10 -4
  122. package/dist/tab-locks.d.ts +63 -0
  123. package/dist/tab-locks.js +179 -0
  124. package/dist/tools.d.ts +38 -0
  125. package/dist/tools.js +20 -1
  126. package/dist/tuning.d.ts +14 -0
  127. package/dist/tuning.js +9 -0
  128. package/dist/upstream.d.ts +11 -0
  129. package/dist/vault.js +5 -4
  130. package/npm-shrinkwrap.json +6 -5
  131. package/package.json +13 -7
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
@@ -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.
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, and challenges in the last 7 days.
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. */