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
package/dist/api.js CHANGED
@@ -6,6 +6,10 @@ import { assertIdentityId, identityDir } from "./ids.js";
6
6
  import { loginIdentity } from "./login.js";
7
7
  import { reputationReport } from "./reputation.js";
8
8
  import { exportSession, importSession, readSessionExport } from "./session-export.js";
9
+ import { flowsDir, listFlows, readFlow, removeFlow } from "./flows.js";
10
+ import { listRecordings, openTraceViewer, recordingsDir, traceViewerCommand } from "./recordings.js";
11
+ import { replayFlow } from "./replay.js";
12
+ import { liveLink, livePause, liveResume, liveStatus } from "./live-client.js";
9
13
  import { parseTotpSecret } from "./totp.js";
10
14
  import { vaultAdd, vaultClear, vaultList, vaultRemove, vaultSetSubmit } from "./vault.js";
11
15
  import { checkIdentitySettings, identitySettingsPath, writeIdentitySettings } from "./settings.js";
@@ -22,10 +26,20 @@ import { manifestSnippet } from "./snippet.js";
22
26
  *
23
27
  * `test/api.test.ts` lists the members, so a change here cannot ship without the version.
24
28
  */
25
- export const API_VERSION = Object.freeze({ major: 1, minor: 2 });
29
+ export const API_VERSION = Object.freeze({ major: 1, minor: 10 });
26
30
  /**
27
31
  * The functions turno-cli calls: identities, their settings, login, doctor, reputation, bench
28
- * (1.1) the credential vault and (1.2) session export and import.
32
+ * (1.1) the credential vault, (1.2) session export and import, (1.3) the `humanize` key of
33
+ * identity.json (no new member: `writeIdentitySettings` accepts it, an older package refuses it)
34
+ * (1.4) the `sharing` key of identity.json and `manifestSnippet(id, { sharing })`, (1.5) the
35
+ * `engine` and `attach` keys of identity.json and the engine checks of `runDoctor`, (1.6) the
36
+ * `record` key of identity.json, saved flows, replay and recordings, (1.7) the `act` and
37
+ * `captcha` keys of identity.json (no new member) and `solved` in each site of
38
+ * `reputationReport`, (1.8) the `tabLocks` key of identity.json and
39
+ * `runDoctor({ servers })`, the mcp.toml servers of each identity, (1.9) the `live` key of
40
+ * identity.json and the live view of a running server (status, pause, resume, a one-time link),
41
+ * and (1.10) the `userAgent` and `proxy` keys and the `"camoufox"` engine of identity.json, and
42
+ * the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them).
29
43
  */
30
44
  export const api = Object.freeze({
31
45
  ENGINES,
@@ -57,5 +71,18 @@ export const api = Object.freeze({
57
71
  exportSession,
58
72
  readSessionExport,
59
73
  importSession,
74
+ flowsDir,
75
+ listFlows,
76
+ readFlow,
77
+ removeFlow,
78
+ replayFlow,
79
+ listRecordings,
80
+ recordingsDir,
81
+ traceViewerCommand,
82
+ openTraceViewer,
83
+ liveStatus,
84
+ livePause,
85
+ liveResume,
86
+ liveLink,
60
87
  });
61
88
  //# sourceMappingURL=api.js.map
package/dist/argv.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import type { EngineFlags } from "./engine.js";
2
+ import type { LiveFlags } from "./live.js";
1
3
  import type { TuningFlags } from "./tuning.js";
2
4
  /**
3
5
  * Turns `turno-browser-mcp [--identity <id>] [playwright-mcp flags]` into the argv for the
@@ -16,8 +18,9 @@ import type { TuningFlags } from "./tuning.js";
16
18
  * Headed mode and `viewport: null` are already the program's defaults for headed runs, so
17
19
  * nothing is added for them; no init scripts are ever added.
18
20
  *
19
- * The tab governor and background throttling flags (`TUNING_FLAGS`) are turno's: they are
20
- * taken out here and win over identity.json.
21
+ * The tab governor, background throttling, humanize and sharing flags (`TUNING_FLAGS`) are turno's: they are
22
+ * taken out here and win over identity.json. So are `--engine <chrome|lightpanda|camoufox>` and `--attach <target>` (`engine.ts`); with either and
23
+ * no identity there is no Chrome profile to create. So are `--live` and `--live-wait <duration>` (`live.ts`), which need an identity.
21
24
  *
22
25
  * An identity holds saved logins, so serving it over HTTP (`--port`, `--host`) lets any local
23
26
  * process drive a signed-in browser without the stdio pipe or mcpd's token. That needs
@@ -38,6 +41,10 @@ export interface BuiltArgv {
38
41
  };
39
42
  /** turno's own flags for the host, when any was given. */
40
43
  tuning?: TuningFlags;
44
+ /** `--engine` and `--attach`, when given. */
45
+ engineFlags?: EngineFlags;
46
+ /** `--live` and `--live-wait`, when given. */
47
+ live?: LiveFlags;
41
48
  }
42
49
  /** The keys of the Playwright MCP config file that turno sets (pinned by the contract test). */
43
50
  export interface PlaywrightMcpConfig {
@@ -61,12 +68,19 @@ export declare const TUNING_FLAGS: {
61
68
  readonly "--park-after": "<duration>";
62
69
  readonly "--close-after": "<duration>";
63
70
  readonly "--background-throttling": "";
71
+ readonly "--humanize": "<off|light|full|adaptive>";
72
+ readonly "--sharing": "<session|tabs>";
64
73
  };
65
74
  /** Removes turno's tuning flags (`TUNING_FLAGS`) from args and returns their values. */
66
75
  export declare function extractTuning(args: string[]): {
67
76
  tuning?: TuningFlags;
68
77
  rest: string[];
69
78
  };
79
+ /** Removes `--engine` and `--attach` from args and returns their values, checked. */
80
+ export declare function extractEngine(args: string[]): {
81
+ engineFlags?: EngineFlags;
82
+ rest: string[];
83
+ };
70
84
  /** Removes `--identity <id>` / `--identity=<id>` from args and returns the id. */
71
85
  export declare function extractIdentity(args: string[]): {
72
86
  identity?: string;
package/dist/argv.js CHANGED
@@ -2,7 +2,10 @@ import { mkdtempSync } from "node:fs";
2
2
  import { tmpdir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { browserPaths as paths } from "turno-core/paths";
5
+ import { HUMANIZE_LEVELS } from "./humanize.js";
5
6
  import { assertIdentityId, identityDir } from "./identities.js";
7
+ import { MAX_LIVE_WAIT_MS, MIN_LIVE_WAIT_MS } from "./settings.js";
8
+ import { parseAttachTarget } from "./engine-attach.js";
6
9
  import { parseDuration } from "./units.js";
7
10
  /** How long Chrome stays open without a tool call, unless TURNO_BROWSER_IDLE says otherwise. */
8
11
  export const DEFAULT_BROWSER_IDLE_MS = 15 * 60_000;
@@ -69,6 +72,8 @@ export const TUNING_FLAGS = {
69
72
  "--park-after": "<duration>",
70
73
  "--close-after": "<duration>",
71
74
  "--background-throttling": "",
75
+ "--humanize": "<off|light|full|adaptive>",
76
+ "--sharing": "<session|tabs>",
72
77
  };
73
78
  function tuningValue(flag, value, out) {
74
79
  if (flag === "--max-tabs") {
@@ -76,11 +81,21 @@ function tuningValue(flag, value, out) {
76
81
  throw new Error(`--max-tabs must be a whole number from 0 (no cap) to 100, not "${value}"`);
77
82
  out.maxTabs = Number(value);
78
83
  }
84
+ else if (flag === "--humanize") {
85
+ if (!HUMANIZE_LEVELS.includes(value))
86
+ throw new Error(`--humanize must be ${HUMANIZE_LEVELS.join(", ")}, not "${value}"`);
87
+ out.humanize = value;
88
+ }
79
89
  else if (flag === "--popups") {
80
90
  if (value !== "close" && value !== "keep")
81
91
  throw new Error(`--popups must be "close" or "keep", not "${value}"`);
82
92
  out.popups = value;
83
93
  }
94
+ else if (flag === "--sharing") {
95
+ if (value !== "session" && value !== "tabs")
96
+ throw new Error(`--sharing must be "session" (one agent session at a time) or "tabs", not "${value}"`);
97
+ out.sharing = value;
98
+ }
84
99
  else {
85
100
  const ms = parseDuration(value);
86
101
  if (ms === undefined)
@@ -124,6 +139,70 @@ export function extractTuning(args) {
124
139
  }
125
140
  return any ? { tuning: out, rest } : { rest };
126
141
  }
142
+ /** The value of `--flag v` or `--flag=v` at `args[i]`, and how many items it took. */
143
+ function valueAt(args, i, flag) {
144
+ const a = args[i];
145
+ if (a.startsWith(`${flag}=`))
146
+ return { value: a.slice(flag.length + 1), used: 1 };
147
+ if (a !== flag)
148
+ return undefined;
149
+ const v = args[i + 1];
150
+ if (v === undefined || v.startsWith("--"))
151
+ throw new Error(`${flag} needs a value`);
152
+ return { value: v, used: 2 };
153
+ }
154
+ /** Removes `--engine` and `--attach` from args and returns their values, checked. */
155
+ export function extractEngine(args) {
156
+ const rest = [];
157
+ const out = {};
158
+ for (let i = 0; i < args.length; i++) {
159
+ const engine = valueAt(args, i, "--engine");
160
+ const attach = engine ? undefined : valueAt(args, i, "--attach");
161
+ if (engine) {
162
+ if (engine.value !== "chrome" && engine.value !== "lightpanda" && engine.value !== "camoufox")
163
+ throw new Error(`--engine must be "chrome", "lightpanda" (read mode) or "camoufox", not "${engine.value}"`);
164
+ out.engine = engine.value;
165
+ i += engine.used - 1;
166
+ }
167
+ else if (attach) {
168
+ const target = parseAttachTarget(attach.value);
169
+ if ("error" in target)
170
+ throw new Error(target.error.replace(/^attach/, "--attach"));
171
+ out.attach = attach.value.trim();
172
+ i += attach.used - 1;
173
+ }
174
+ else
175
+ rest.push(args[i]);
176
+ }
177
+ if ((out.engine === "lightpanda" || out.engine === "camoufox") && out.attach !== undefined)
178
+ throw new Error(`--attach and --engine ${out.engine} do not go together: pick one`);
179
+ return out.engine !== undefined || out.attach !== undefined ? { engineFlags: out, rest } : { rest };
180
+ }
181
+ /** Removes `--live` and `--live-wait <duration>` from args and returns their values, checked. */
182
+ function extractLive(args) {
183
+ const rest = [];
184
+ const out = {};
185
+ for (let i = 0; i < args.length; i++) {
186
+ const a = args[i];
187
+ if (a === "--live") {
188
+ out.live = true;
189
+ continue;
190
+ }
191
+ if (a.startsWith("--live="))
192
+ throw new Error("--live takes no value");
193
+ const wait = valueAt(args, i, "--live-wait");
194
+ if (!wait) {
195
+ rest.push(a);
196
+ continue;
197
+ }
198
+ const ms = parseDuration(wait.value);
199
+ if (ms === undefined || ms < MIN_LIVE_WAIT_MS || ms > MAX_LIVE_WAIT_MS)
200
+ throw new Error(`--live-wait must be a duration from "5s" to "30m", like "2m", not "${wait.value}"`);
201
+ out.waitMs = ms;
202
+ i += wait.used - 1;
203
+ }
204
+ return out.live !== undefined || out.waitMs !== undefined ? { live: out, rest } : { rest };
205
+ }
127
206
  /** Removes `--identity <id>` / `--identity=<id>` from args and returns the id. */
128
207
  export function extractIdentity(args) {
129
208
  const rest = [];
@@ -154,12 +233,28 @@ function defaultTempDir() {
154
233
  export function buildArgv(rawArgs, options = {}) {
155
234
  const env = options.env ?? process.env;
156
235
  const { identity, rest: afterIdentity } = extractIdentity(rawArgs);
157
- const { tuning, rest } = extractTuning(afterIdentity);
236
+ const { tuning, rest: afterTuning } = extractTuning(afterIdentity);
237
+ const { engineFlags, rest: afterEngine } = extractEngine(afterTuning);
238
+ const { live, rest } = extractLive(afterEngine);
239
+ // The live view's control socket and live.json belong to the identity's state folder.
240
+ if (live && identity === undefined)
241
+ throw new Error("--live and --live-wait apply only with --identity");
158
242
  const allowHttp = rest.includes(ALLOW_HTTP_IDENTITY);
159
243
  const args = rest.filter((a) => a !== ALLOW_HTTP_IDENTITY);
160
244
  guardHttp(args, identity, allowHttp);
161
245
  const external = hasAny(args, EXTERNAL_BROWSER);
162
- const out = { args, ...(tuning ? { tuning } : {}) };
246
+ const out = {
247
+ args,
248
+ ...(tuning ? { tuning } : {}),
249
+ ...(engineFlags ? { engineFlags } : {}),
250
+ ...(live ? { live } : {}),
251
+ };
252
+ const otherEngine = engineFlags?.engine === "lightpanda" || engineFlags?.engine === "camoufox" || engineFlags?.attach !== undefined;
253
+ if (otherEngine) {
254
+ const clash = ["--isolated", "--user-data-dir", ...EXTERNAL_BROWSER].find((f) => hasFlag(args, f));
255
+ if (clash)
256
+ throw new Error(`${engineFlags?.attach !== undefined ? "--attach" : `--engine ${engineFlags?.engine}`} cannot be combined with ${clash}`);
257
+ }
163
258
  if (identity !== undefined) {
164
259
  const clash = ["--user-data-dir", "--isolated", ...EXTERNAL_BROWSER].find((f) => hasFlag(args, f));
165
260
  if (clash)
@@ -172,7 +267,9 @@ export function buildArgv(rawArgs, options = {}) {
172
267
  out.tempDir ??= (options.makeTempDir ?? defaultTempDir)();
173
268
  return out.tempDir;
174
269
  };
175
- if (!external && !hasFlag(args, "--user-data-dir") && !hasFlag(args, "--isolated")) {
270
+ // Read mode, Camoufox and attach mode without an identity start no Chrome, so they need no profile.
271
+ const needsProfile = !(otherEngine && identity === undefined);
272
+ if (!external && needsProfile && !hasFlag(args, "--user-data-dir") && !hasFlag(args, "--isolated")) {
176
273
  out.userDataDir = identity !== undefined ? identityDir(identity, env) : join(makeTemp(), "profile");
177
274
  args.push("--user-data-dir", out.userDataDir);
178
275
  }
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,11 @@
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 { engineChoice } from "../engine.js";
6
+ import { lightpandaCookieJar, sweepOrphanLightpandas } from "../engine-lightpanda.js";
5
7
  import { runHost } from "../host.js";
6
8
  import { installShutdownGuard, sweepOrphan } from "../lifecycle.js";
9
+ import { readIdentitySettings } from "../settings.js";
7
10
  /**
8
11
  * turno-browser-mcp [--identity <id>] [playwright-mcp flags]
9
12
  *
@@ -17,7 +20,8 @@ import { installShutdownGuard, sweepOrphan } from "../lifecycle.js";
17
20
  const HELP = `turno-browser-mcp: a browser MCP server that drives your installed Chrome, with one
18
21
  persistent profile per identity (turno identity add browser:<id>).
19
22
 
20
- --identity <id> use the identity's saved profile (served one session at a time by mcpd)
23
+ --identity <id> use the identity's saved profile (served one session at a time by
24
+ mcpd, unless the identity's "sharing" is "tabs")
21
25
  --allow-http-identity allow --port or --host together with --identity; the server then
22
26
  binds to 127.0.0.1 only. Any local process can use that browser.
23
27
 
@@ -34,11 +38,44 @@ Tabs (these flags win over the identity's identity.json):
34
38
  --close-after <duration> close a page unused this long (default 15m; 0: never)
35
39
  --background-throttling let Chrome slow down tabs that are not in front (default off); the
36
40
  agent's tab is brought to the front before each call
41
+ --sharing <session|tabs> "tabs": several agent sessions use the browser at once, each in
42
+ its own tabs, which it locks (default "session", one at a time;
43
+ mcp.toml then needs exclusive = false for this server)
44
+
45
+ Input (wins over the identity's identity.json):
46
+ --humanize <level> off (default), light, full or adaptive: the pointer travels a curve
47
+ to a point inside the target, keys are typed with human delays;
48
+ full adds overshoot, reading pauses and wheel scrolling; adaptive is
49
+ light, and full on a site that showed a challenge page
50
+
51
+ Engines (these flags win over the identity's identity.json; all off by default):
52
+ --engine lightpanda read mode: Lightpanda instead of Chrome, for reading pages
53
+ (navigate, snapshot, find, click a link, evaluate); other tools are
54
+ refused. Needs lightpanda on PATH or TURNO_LIGHTPANDA_PATH
55
+ --engine camoufox Camoufox (a Firefox build) instead of Chrome, with its own profile;
56
+ not recommended for your own accounts. Needs Camoufox and
57
+ playwright-core (turno browser doctor says how); never downloaded
58
+ --engine chrome the default; turns off an identity's read, Camoufox or attach mode
59
+ --attach <target> connect to a Chrome you already have open instead of launching
60
+ one: "auto" (your default Chrome profile, after you turn on remote
61
+ debugging at chrome://inspect/#remote-debugging), a Chrome user
62
+ data dir, or a loopback endpoint. The agent sees every window of
63
+ that profile; turno closes only the tabs it opened
64
+
65
+ Live view (wins over the identity's identity.json; off by default):
66
+ --live serve a view of the agent's tab on 127.0.0.1 (turno browser live
67
+ <id> opens it) and let you pause the agent to take the controls
68
+ --live-wait <duration> how long a call waits while you have the agent paused (default 2m,
69
+ "5s" to "30m"); then it fails and tells the agent you still have it
37
70
 
38
71
  Examples:
39
72
  turno-browser-mcp --identity work
40
73
  turno-browser-mcp --identity work --max-tabs 4 --park-after 2m
74
+ turno-browser-mcp --identity work --humanize light
41
75
  turno-browser-mcp --headless --popups keep
76
+ turno-browser-mcp --engine lightpanda
77
+ turno-browser-mcp --attach auto
78
+ turno-browser-mcp --identity work --live
42
79
 
43
80
  Every other flag is a Playwright MCP flag:
44
81
  `;
@@ -73,8 +110,28 @@ if (built.userDataDir && !help) {
73
110
  }
74
111
  installShutdownGuard(built.userDataDir);
75
112
  }
113
+ if (!help && readMode(built)) {
114
+ const jar = built.identity !== undefined ? lightpandaCookieJar(built.identity, process.env) : undefined;
115
+ for (const swept of await sweepOrphanLightpandas(jar)) {
116
+ process.stderr.write(swept.action === "survived"
117
+ ? `turno-browser-mcp: a Lightpanda an earlier run left open (pid ${swept.pid}) did not stop\n`
118
+ : `turno-browser-mcp: closed a Lightpanda an earlier run left open (pid ${swept.pid})\n`);
119
+ }
120
+ }
121
+ /** True when this server runs on Lightpanda (`--engine lightpanda`, or the identity's engine). */
122
+ function readMode(argv) {
123
+ try {
124
+ const settings = argv.identity !== undefined ? readIdentitySettings(argv.identity, process.env) : undefined;
125
+ return engineChoice(argv.engineFlags ?? {}, settings).kind === "lightpanda";
126
+ }
127
+ catch {
128
+ return false; // the launch reports a bad identity.json or flag
129
+ }
130
+ }
76
131
  await runHost(built.args, {
77
132
  ...(built.identity !== undefined ? { identity: { id: built.identity, env: process.env } } : {}),
78
133
  ...(built.tuning ? { tuning: built.tuning } : {}),
134
+ ...(built.engineFlags ? { engineFlags: built.engineFlags } : {}),
135
+ ...(built.live ? { live: built.live } : {}),
79
136
  });
80
137
  //# sourceMappingURL=mcp.js.map
@@ -0,0 +1,77 @@
1
+ import type { TurnoTool } from "./tools.js";
2
+ /**
3
+ * Captcha solving, off by default (identity.json `captcha`). `browser_solve_captcha` finds a
4
+ * captcha widget on the current tab, sends its kind, site key and the page URL to the solver
5
+ * service the person configured, and puts the token it returns into the page's response field
6
+ * (and the widget's callback, when it names one). The agent then submits the form itself.
7
+ *
8
+ * What it is and is not:
9
+ *
10
+ * - The solver is a third party: it sees the page URL and the widget, and usually loads the
11
+ * page on its own machines to answer. Its key comes from the secret store through a
12
+ * `keychain:` reference, joins the redactor, and never appears in a tool argument or result.
13
+ * - It answers only the widgets that hand back a token (`WIDGETS`). A full-page "checking your
14
+ * browser" interstitial, a "verify it's you" prompt or a block page is left to the person.
15
+ * - Every attempt, solved or not, is one line in the identity's reputation log (`reputation.ts`)
16
+ * with the host name, the widget kind and the provider: never the token or the key.
17
+ * - Many sites' terms forbid solving their captchas by machine; the docs say so and say it is
18
+ * meant for the person's own accounts.
19
+ */
20
+ /** The widgets a token answers, with the task type of the task protocol and where the token goes. */
21
+ export declare const WIDGETS: {
22
+ readonly recaptcha: {
23
+ readonly task: "RecaptchaV2TaskProxyless";
24
+ readonly fields: readonly ["g-recaptcha-response"];
25
+ readonly label: "reCAPTCHA v2";
26
+ };
27
+ readonly hcaptcha: {
28
+ readonly task: "HCaptchaTaskProxyless";
29
+ readonly fields: readonly ["h-captcha-response", "g-recaptcha-response"];
30
+ readonly label: "hCaptcha";
31
+ };
32
+ readonly turnstile: {
33
+ readonly task: "TurnstileTaskProxyless";
34
+ readonly fields: readonly ["cf-turnstile-response"];
35
+ readonly label: "Turnstile";
36
+ };
37
+ };
38
+ type WidgetKind = keyof typeof WIDGETS;
39
+ /** A widget found on a page. The site key is public: it is in the page's markup. */
40
+ interface CaptchaWidget {
41
+ kind: WidgetKind;
42
+ siteKey: string;
43
+ /** reCAPTCHA's invisible mode. */
44
+ invisible?: boolean;
45
+ /** The global function the widget calls with the token (`data-callback`), when it names one. */
46
+ callback?: string;
47
+ }
48
+ interface SolveRequest {
49
+ widget: CaptchaWidget;
50
+ pageUrl: string;
51
+ signal?: AbortSignal;
52
+ }
53
+ /** A solver service, behind one method. */
54
+ export interface CaptchaSolver {
55
+ /** How the result names it: "task-api at solver.example.com". */
56
+ readonly label: string;
57
+ /** The provider id for the reputation log. */
58
+ readonly provider: string;
59
+ solve(request: SolveRequest): Promise<{
60
+ token: string;
61
+ }>;
62
+ }
63
+ type Fetch = typeof fetch;
64
+ /**
65
+ * The task protocol many solver services share: `POST <endpoint>/createTask` with the account
66
+ * key and a task, then `POST <endpoint>/getTaskResult` until the task is ready. Errors come back
67
+ * as `errorId` with `errorCode` and `errorDescription`.
68
+ */
69
+ export declare function taskApiSolver(options: {
70
+ endpoint: string;
71
+ key: string;
72
+ fetch?: Fetch;
73
+ /** Waits between polls (ms); the last one repeats. Default: 1 s, 2 s, then every 3 s. */
74
+ polls?: readonly number[];
75
+ }): CaptchaSolver;
76
+ export declare function solveCaptchaTool(): TurnoTool;
77
+ export {};