turno-browser 0.2.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 (121) hide show
  1. package/CHANGELOG.md +228 -0
  2. package/README.md +205 -16
  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 +96 -0
  8. package/dist/api.js +88 -0
  9. package/dist/argv.d.ts +55 -3
  10. package/dist/argv.js +190 -10
  11. package/dist/batch.d.ts +19 -0
  12. package/dist/batch.js +148 -0
  13. package/dist/bench.d.ts +1 -1
  14. package/dist/bench.js +21 -5
  15. package/dist/bin/mcp.js +108 -12
  16. package/dist/captcha.d.ts +77 -0
  17. package/dist/captcha.js +333 -0
  18. package/dist/cdp-relay.d.ts +20 -0
  19. package/dist/cdp-relay.js +101 -0
  20. package/dist/chrome-features.d.ts +23 -0
  21. package/dist/chrome-features.js +44 -0
  22. package/dist/detectors.d.ts +11 -0
  23. package/dist/detectors.js +46 -4
  24. package/dist/diagnose.d.ts +45 -0
  25. package/dist/diagnose.js +326 -0
  26. package/dist/doctor.d.ts +85 -0
  27. package/dist/doctor.js +556 -0
  28. package/dist/engine-attach.d.ts +27 -0
  29. package/dist/engine-attach.js +165 -0
  30. package/dist/engine-camoufox.d.ts +32 -0
  31. package/dist/engine-camoufox.js +270 -0
  32. package/dist/engine-lightpanda.d.ts +72 -0
  33. package/dist/engine-lightpanda.js +292 -0
  34. package/dist/engine.d.ts +119 -0
  35. package/dist/engine.js +355 -0
  36. package/dist/flows.d.ts +127 -0
  37. package/dist/flows.js +294 -0
  38. package/dist/governor.d.ts +119 -0
  39. package/dist/governor.js +325 -0
  40. package/dist/health.d.ts +60 -0
  41. package/dist/health.js +86 -0
  42. package/dist/host.d.ts +95 -0
  43. package/dist/host.js +1181 -0
  44. package/dist/human-input.d.ts +84 -0
  45. package/dist/human-input.js +443 -0
  46. package/dist/humanize.d.ts +123 -0
  47. package/dist/humanize.js +241 -0
  48. package/dist/identities.d.ts +23 -10
  49. package/dist/identities.js +45 -37
  50. package/dist/idle-timer.d.ts +12 -0
  51. package/dist/idle-timer.js +25 -0
  52. package/dist/ids.d.ts +9 -0
  53. package/dist/ids.js +34 -0
  54. package/dist/index.d.ts +21 -6
  55. package/dist/index.js +19 -18
  56. package/dist/lifecycle.d.ts +99 -0
  57. package/dist/lifecycle.js +172 -0
  58. package/dist/live-client.d.ts +22 -0
  59. package/dist/live-client.js +93 -0
  60. package/dist/live-page.d.ts +11 -0
  61. package/dist/live-page.js +143 -0
  62. package/dist/live-server.d.ts +173 -0
  63. package/dist/live-server.js +640 -0
  64. package/dist/live.d.ts +120 -0
  65. package/dist/live.js +203 -0
  66. package/dist/login-tool.d.ts +45 -0
  67. package/dist/login-tool.js +233 -0
  68. package/dist/login.d.ts +8 -3
  69. package/dist/login.js +65 -26
  70. package/dist/network-chrome.d.ts +74 -0
  71. package/dist/network-chrome.js +178 -0
  72. package/dist/network.d.ts +125 -0
  73. package/dist/network.js +263 -0
  74. package/dist/opt-in-settings.d.ts +69 -0
  75. package/dist/opt-in-settings.js +151 -0
  76. package/dist/patchright.d.ts +4 -2
  77. package/dist/patchright.js +4 -2
  78. package/dist/recorder.d.ts +88 -0
  79. package/dist/recorder.js +538 -0
  80. package/dist/recordings.d.ts +116 -0
  81. package/dist/recordings.js +474 -0
  82. package/dist/redact.d.ts +34 -0
  83. package/dist/redact.js +135 -0
  84. package/dist/replay.d.ts +20 -0
  85. package/dist/replay.js +382 -0
  86. package/dist/reputation.d.ts +89 -0
  87. package/dist/reputation.js +203 -0
  88. package/dist/resources.d.ts +76 -0
  89. package/dist/resources.js +341 -0
  90. package/dist/runtime-lock.d.ts +59 -0
  91. package/dist/runtime-lock.js +131 -0
  92. package/dist/sealed.d.ts +8 -0
  93. package/dist/sealed.js +96 -0
  94. package/dist/session-export.d.ts +67 -0
  95. package/dist/session-export.js +194 -0
  96. package/dist/session.d.ts +20 -0
  97. package/dist/session.js +30 -0
  98. package/dist/settings.d.ts +246 -0
  99. package/dist/settings.js +530 -0
  100. package/dist/sharing.d.ts +96 -0
  101. package/dist/sharing.js +269 -0
  102. package/dist/snippet.d.ts +8 -0
  103. package/dist/snippet.js +22 -0
  104. package/dist/tab-locks.d.ts +63 -0
  105. package/dist/tab-locks.js +179 -0
  106. package/dist/tools.d.ts +111 -0
  107. package/dist/tools.js +59 -0
  108. package/dist/totp.d.ts +32 -0
  109. package/dist/totp.js +82 -0
  110. package/dist/tuning.d.ts +76 -0
  111. package/dist/tuning.js +69 -0
  112. package/dist/units.d.ts +8 -0
  113. package/dist/units.js +20 -0
  114. package/dist/upstream.d.ts +243 -0
  115. package/dist/upstream.js +46 -0
  116. package/dist/vault.d.ts +91 -0
  117. package/dist/vault.js +273 -0
  118. package/npm-shrinkwrap.json +1074 -3
  119. package/package.json +5 -4
  120. package/dist/paths.d.ts +0 -17
  121. package/dist/paths.js +0 -17
package/dist/batch.js ADDED
@@ -0,0 +1,148 @@
1
+ import { upstream } from "./upstream.js";
2
+ /**
3
+ * `browser_batch`: several stock actions in one tool call. Each action runs through
4
+ * the same path as a call of its own (the tab governor, the click diagnosis), but without the
5
+ * page snapshot a stock action adds to its result; the batch returns one line per action and,
6
+ * when asked, one snapshot after the last. It stops at the first action that fails.
7
+ *
8
+ * It saves the model a round trip per action and the server an accessibility snapshot per
9
+ * action (`bench/browser-roundtrips.mjs` measures both).
10
+ */
11
+ /** Most actions in one batch. */
12
+ export const MAX_BATCH = 20;
13
+ /** Longest text kept from one action's result section. */
14
+ const RESULT_CHARS = 400;
15
+ /** The sections of an upstream result text (`### Title` then the body). */
16
+ export function sections(text) {
17
+ const out = new Map();
18
+ for (const part of text.split(/^### /m).slice(1)) {
19
+ const nl = part.indexOf("\n");
20
+ if (nl < 0)
21
+ continue;
22
+ out.set(part.slice(0, nl), part.slice(nl + 1).trim());
23
+ }
24
+ return out;
25
+ }
26
+ export function clip(text, max = RESULT_CHARS) {
27
+ return text.length > max ? `${text.slice(0, max - 3)}...` : text;
28
+ }
29
+ /** What an action acted on, for its line: `browser_click e5`, `browser_navigate https://...`. */
30
+ function label(tool, args) {
31
+ const what = args.target ?? args.startTarget ?? args.url ?? args.key ?? args.action ?? args.text;
32
+ return what === undefined ? tool : `${tool} ${clip(String(what), 80)}`;
33
+ }
34
+ export function textOf(result) {
35
+ return result.content
36
+ .filter((c) => c.type === "text")
37
+ .map((c) => c.text)
38
+ .join("\n");
39
+ }
40
+ function batchSchema() {
41
+ const z = upstream().utils.z;
42
+ return {
43
+ name: "browser_batch",
44
+ title: "Run several browser actions",
45
+ description: [
46
+ "Run several browser actions in order in one call, stopping at the first one that fails.",
47
+ "Each action names a browser tool (browser_navigate, browser_click, browser_type, browser_select_option, browser_press_key, browser_hover, browser_wait_for, ...) and its arguments, exactly as that tool takes them.",
48
+ "Returns one short line per action instead of a snapshot after each, and one page snapshot after the last action when snapshot is true.",
49
+ "Refs come from the snapshot taken before the batch: when an action changes the page, later refs may no longer exist, so batch actions on one page (filling a form) and take a snapshot after.",
50
+ ].join(" "),
51
+ inputSchema: z.object({
52
+ actions: z
53
+ .array(z.object({
54
+ tool: z.string().describe("A browser tool name, for example browser_click"),
55
+ arguments: z.record(z.string(), z.unknown()).optional().describe("The tool's arguments, as it takes them"),
56
+ }))
57
+ .min(1)
58
+ .max(MAX_BATCH)
59
+ .describe(`The actions, in order (at most ${MAX_BATCH})`),
60
+ snapshot: z.boolean().optional().describe("Return a snapshot of the page after the last action (default false)"),
61
+ }),
62
+ type: "action",
63
+ };
64
+ }
65
+ /** The tool. Its schema is built on first use, so importing the registry does not load the bundle. */
66
+ export function batchTool() {
67
+ let schema;
68
+ return {
69
+ get schema() {
70
+ schema ??= batchSchema();
71
+ return schema;
72
+ },
73
+ async handle(ctx, params) {
74
+ const actions = params.actions;
75
+ const stock = ctx.stock;
76
+ if (!stock)
77
+ throw new Error("browser_batch needs the browser host");
78
+ // Check every action before running any, so a typo in the last one runs nothing.
79
+ const problems = [];
80
+ actions.forEach((a, i) => {
81
+ const schema = stock.schemas.get(a.tool);
82
+ if (!schema) {
83
+ problems.push(`action ${i + 1}: "${a.tool}" is not a browser tool of this server${a.tool === "browser_batch" ? " (a batch cannot hold a batch)" : ""}`);
84
+ return;
85
+ }
86
+ const parsed = schema.safeParse(a.arguments ?? {});
87
+ if (!parsed.success)
88
+ problems.push(`action ${i + 1} (${a.tool}): invalid arguments: ${stock.formatError(parsed.error)}`);
89
+ });
90
+ if (problems.length) {
91
+ return { content: [{ type: "text", text: `### Error\nNothing ran.\n${problems.join("\n")}` }], isError: true };
92
+ }
93
+ const lines = [];
94
+ const attachments = [];
95
+ const notes = [];
96
+ let failure;
97
+ for (const [i, a] of actions.entries()) {
98
+ const args = a.arguments ?? {};
99
+ const result = await stock.call(a.tool, args, { snapshot: false });
100
+ const parts = sections(textOf(result));
101
+ const governor = parts.get("Tab governor");
102
+ if (governor)
103
+ notes.push(governor);
104
+ attachments.push(...result.content.filter((c) => c.type !== "text"));
105
+ if (result.isError) {
106
+ lines.push(`${i + 1}. ${label(a.tool, args)}: failed`);
107
+ const error = parts.get("Error") ?? textOf(result);
108
+ const left = actions.length - i - 1;
109
+ failure = `Action ${i + 1} of ${actions.length} (${label(a.tool, args)}) failed${left ? `; the ${left === 1 ? "last action" : `last ${left} actions`} did not run` : ""}.\n${error}`;
110
+ break;
111
+ }
112
+ const res = parts.get("Result");
113
+ lines.push(`${i + 1}. ${label(a.tool, args)}: ok${res ? `\n ${clip(res).replace(/\n/g, "\n ")}` : ""}`);
114
+ const modal = parts.get("Modal state");
115
+ if (modal)
116
+ lines.push(` ${clip(modal).replace(/\n/g, "\n ")}`);
117
+ }
118
+ const out = [];
119
+ if (failure)
120
+ out.push("### Error", failure);
121
+ out.push("### Batch", ...lines);
122
+ if (params.snapshot === true && !failure) {
123
+ const snap = await stock.call("browser_snapshot", {}, { snapshot: true });
124
+ const parts = sections(textOf(snap));
125
+ const governor = parts.get("Tab governor");
126
+ if (governor)
127
+ notes.push(governor);
128
+ for (const title of ["Open tabs", "Page", "Modal state", "Snapshot", "Events"]) {
129
+ const body = parts.get(title);
130
+ if (body)
131
+ out.push(`### ${title}`, body);
132
+ }
133
+ }
134
+ else {
135
+ const page = await stock.page();
136
+ if (page)
137
+ out.push("### Page", `- Page URL: ${page.url}`, ...(page.title ? [`- Page Title: ${page.title}`] : []));
138
+ }
139
+ if (notes.length)
140
+ out.push("### Tab governor", ...notes);
141
+ return {
142
+ content: [{ type: "text", text: out.join("\n") }, ...attachments],
143
+ ...(failure ? { isError: true } : {}),
144
+ };
145
+ },
146
+ };
147
+ }
148
+ //# sourceMappingURL=batch.js.map
package/dist/bench.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * `turno browser bench`: runs several browser engines against public bot detectors and the
3
- * user's own URLs, so engine choices rest on measurements (ADR 0003, 0005).
3
+ * user's own URLs, so engine choices rest on measurements.
4
4
  */
5
5
  /**
6
6
  * Engine ids name the browser and its mode: Chrome headed and headless through the package's
package/dist/bench.js CHANGED
@@ -2,12 +2,12 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
2
2
  import { tmpdir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { pathToFileURL } from "node:url";
5
+ import { browserPaths as paths } from "turno-core/paths";
5
6
  import { detectChallenge, parseRebrowser, parseSannysoft } from "./detectors.js";
6
- import { paths } from "./paths.js";
7
7
  import { resolveFrom } from "./patchright.js";
8
8
  /**
9
9
  * `turno browser bench`: runs several browser engines against public bot detectors and the
10
- * user's own URLs, so engine choices rest on measurements (ADR 0003, 0005).
10
+ * user's own URLs, so engine choices rest on measurements.
11
11
  */
12
12
  /**
13
13
  * Engine ids name the browser and its mode: Chrome headed and headless through the package's
@@ -141,7 +141,13 @@ export async function runBench(options = {}) {
141
141
  for (const url of options.urls ?? [])
142
142
  targets.push({ target: "url", url });
143
143
  const started = new Date();
144
- const report = { version: 1, startedAt: started.toISOString(), finishedAt: "", engines: [], results: [] };
144
+ const report = {
145
+ version: 1,
146
+ startedAt: started.toISOString(),
147
+ finishedAt: "",
148
+ engines: [],
149
+ results: [],
150
+ };
145
151
  for (const engine of engines) {
146
152
  const reason = unavailableReason(engine);
147
153
  if (reason) {
@@ -167,7 +173,14 @@ export async function runBench(options = {}) {
167
173
  report.results.push(await runTarget(session, engine, t.target, t.url, settleMs));
168
174
  }
169
175
  catch (err) {
170
- report.results.push({ engine, target: t.target, url: t.url, ok: false, summary: "error", error: firstLine(err) });
176
+ report.results.push({
177
+ engine,
178
+ target: t.target,
179
+ url: t.url,
180
+ ok: false,
181
+ summary: "error",
182
+ error: firstLine(err),
183
+ });
171
184
  }
172
185
  }
173
186
  }
@@ -200,7 +213,10 @@ export function formatBenchTable(report) {
200
213
  }
201
214
  const widths = [0, 1, 2].map((i) => Math.max(...rows.map((r) => r[i].length)));
202
215
  return rows
203
- .map((r) => r.map((cell, i) => (i < 3 ? cell.padEnd(widths[i]) : cell)).join(" ").trimEnd())
216
+ .map((r) => r
217
+ .map((cell, i) => (i < 3 ? cell.padEnd(widths[i]) : cell))
218
+ .join(" ")
219
+ .trimEnd())
204
220
  .join("\n");
205
221
  }
206
222
  //# sourceMappingURL=bench.js.map
package/dist/bin/mcp.js CHANGED
@@ -1,24 +1,86 @@
1
1
  #!/usr/bin/env node
2
- import { mkdirSync, rmSync } from "node:fs";
3
- import { createRequire } from "node:module";
2
+ import { mkdirSync, rmSync, writeFileSync } from "node:fs";
3
+ import { dirname } from "node:path";
4
4
  import { buildArgv } from "../argv.js";
5
- import { mcpEntryPath } from "../patchright.js";
5
+ import { engineChoice } from "../engine.js";
6
+ import { lightpandaCookieJar, sweepOrphanLightpandas } from "../engine-lightpanda.js";
7
+ import { runHost } from "../host.js";
8
+ import { installShutdownGuard, sweepOrphan } from "../lifecycle.js";
9
+ import { readIdentitySettings } from "../settings.js";
6
10
  /**
7
11
  * turno-browser-mcp [--identity <id>] [playwright-mcp flags]
8
12
  *
9
- * Runs the Patchright build of the Playwright MCP program in this process with the defaults of
10
- * ADR 0005. Speaks MCP over stdio; `--port` with `--identity` needs `--allow-http-identity`.
13
+ * Serves the Playwright MCP tools of patchright-core from turno's own MCP host, with
14
+ * turno's defaults and lifecycle: a generated config that closes an idle Chrome, a sweep of a
15
+ * Chrome an earlier run left behind on the same profile, and a deadline on shutdown. With
16
+ * `--identity`, the identity module: identity.json applied at launch,
17
+ * a runtime lock while Chrome runs, the session health check and the reputation log.
18
+ * Speaks MCP over stdio; `--port` with `--identity` needs `--allow-http-identity`.
11
19
  */
12
20
  const HELP = `turno-browser-mcp: a browser MCP server that drives your installed Chrome, with one
13
21
  persistent profile per identity (turno identity add browser:<id>).
14
22
 
15
- --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")
16
25
  --allow-http-identity allow --port or --host together with --identity; the server then
17
26
  binds to 127.0.0.1 only. Any local process can use that browser.
18
27
 
19
- Every other flag goes to the Playwright MCP program:
28
+ TURNO_BROWSER_IDLE=15m close Chrome after this long without a tool call (headed too); the
29
+ next call opens it again with the same profile. "0" keeps it open.
30
+ --idle-timeout <ms> and a --config of your own take precedence.
31
+
32
+ Tabs (these flags win over the identity's identity.json):
33
+ --max-tabs <n> most pages open at once, the least recently used closes past it
34
+ (default 8; 0: no cap)
35
+ --popups <close|keep> close popups that open while no tool call runs (default close)
36
+ --park-after <duration> park a page unused this long on about:blank; it loads again on its
37
+ next use (default 5m; 0: never)
38
+ --close-after <duration> close a page unused this long (default 15m; 0: never)
39
+ --background-throttling let Chrome slow down tabs that are not in front (default off); the
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
70
+
71
+ Examples:
72
+ turno-browser-mcp --identity work
73
+ turno-browser-mcp --identity work --max-tabs 4 --park-after 2m
74
+ turno-browser-mcp --identity work --humanize light
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
79
+
80
+ Every other flag is a Playwright MCP flag:
20
81
  `;
21
- if (process.argv.includes("--help") || process.argv.includes("-h"))
82
+ const help = process.argv.includes("--help") || process.argv.includes("-h");
83
+ if (help)
22
84
  process.stdout.write(`${HELP}\n`);
23
85
  let built;
24
86
  try {
@@ -34,8 +96,42 @@ if (built.tempDir) {
34
96
  const dir = built.tempDir;
35
97
  process.on("exit", () => rmSync(dir, { recursive: true, force: true }));
36
98
  }
37
- const entry = mcpEntryPath();
38
- // The program parses process.argv with commander ("node <script> ...flags").
39
- process.argv = [process.argv[0], entry, ...built.args];
40
- createRequire(import.meta.url)(entry);
99
+ if (built.config && !help) {
100
+ mkdirSync(dirname(built.config.path), { recursive: true, mode: 0o700 });
101
+ writeFileSync(built.config.path, `${JSON.stringify(built.config.data, null, 2)}\n`, { mode: 0o600 });
102
+ }
103
+ if (built.userDataDir && !help) {
104
+ const swept = await sweepOrphan(built.userDataDir);
105
+ if (swept.action === "exited" || swept.action === "killed") {
106
+ process.stderr.write(`turno-browser-mcp: closed a Chrome an earlier run left open on this profile (pid ${swept.pid})\n`);
107
+ }
108
+ else if (swept.action === "survived") {
109
+ process.stderr.write(`turno-browser-mcp: a Chrome an earlier run left open on this profile (pid ${swept.pid}) did not stop\n`);
110
+ }
111
+ installShutdownGuard(built.userDataDir);
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
+ }
131
+ await runHost(built.args, {
132
+ ...(built.identity !== undefined ? { identity: { id: built.identity, env: process.env } } : {}),
133
+ ...(built.tuning ? { tuning: built.tuning } : {}),
134
+ ...(built.engineFlags ? { engineFlags: built.engineFlags } : {}),
135
+ ...(built.live ? { live: built.live } : {}),
136
+ });
41
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 {};