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
@@ -0,0 +1,263 @@
1
+ import { secretStore } from "turno-core/secrets";
2
+ /**
3
+ * Opt-in network and user agent settings of an identity (identity.json format 11), both off by
4
+ * default. They are "not recommended": a real Chrome on the user's own connection is already
5
+ * the most coherent browser a site can see, and these settings can only keep it coherent or
6
+ * break it. The docs say what each one costs.
7
+ *
8
+ * `userAgent: "coherent"` presents the identity as the installed Chrome, as one set, verified
9
+ * at every launch:
10
+ *
11
+ * - the user agent string is Chrome's own reduced one for this OS and the installed major
12
+ * version, so a headless Chrome no longer says `HeadlessChrome` (headed, it is unchanged);
13
+ * - the client hints (`Sec-CH-UA*`, `navigator.userAgentData`: brands, full version list,
14
+ * platform, platform version, architecture) and `navigator.platform` stay Chrome's real ones;
15
+ * - the languages and the time zone are the identity's (`languages`/`locale`, `timezone`) or,
16
+ * without them, the system's.
17
+ *
18
+ * The platform and the Chrome version are never configurable. Measured with Chrome 157: no
19
+ * DevTools override reaches `navigator.platform` in a dedicated worker, and a popup's first
20
+ * request carries the real `Sec-CH-UA-Platform` and platform version, so another platform would
21
+ * be a partial override however it is applied (and WebGL, fonts and TLS would still say the real
22
+ * one). A typed user agent string is refused for the same reason.
23
+ *
24
+ * `proxy` sends the identity's traffic through a proxy. The credentials are never written in
25
+ * identity.json: `password` (and `username`, when it is one) is a `keychain:<item>` reference
26
+ * read from the secret store at launch, and both values join the redactor, so no tool result
27
+ * shows them. WebRTC is kept on the proxy (`disable_non_proxied_udp`), so it does not show the
28
+ * direct address.
29
+ */
30
+ /** The values of `userAgent`. */
31
+ const USER_AGENT_MODES = ["coherent"];
32
+ const PROXY_SCHEMES = new Set(["http:", "https:", "socks4:", "socks5:"]);
33
+ const KEYCHAIN = "keychain:";
34
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
35
+ /** Problems with a `proxy.server` value; empty when it is valid. */
36
+ function serverProblems(server) {
37
+ if (typeof server !== "string" || !server.trim())
38
+ return ['proxy.server must be a URL like "http://proxy.example.com:8080"'];
39
+ let url;
40
+ try {
41
+ url = new URL(server);
42
+ }
43
+ catch {
44
+ return [`proxy.server "${server}" is not a URL (like "http://proxy.example.com:8080")`];
45
+ }
46
+ if (!PROXY_SCHEMES.has(url.protocol))
47
+ return ["proxy.server must start with http://, https://, socks4:// or socks5://"];
48
+ if (url.username || url.password)
49
+ return [
50
+ "proxy.server must not carry a user name or password: put the user name in proxy.username and the password in the secret store (proxy.password: keychain:<item>)",
51
+ ];
52
+ if (!url.hostname)
53
+ return ["proxy.server needs a host"];
54
+ if ((url.pathname && url.pathname !== "/") || url.search || url.hash)
55
+ return ["proxy.server is a host and port only, with no path or query"];
56
+ return [];
57
+ }
58
+ /** Problems with the format 11 keys alone (combinations with the engine keys: `networkEngineClash`). */
59
+ export function networkProblems(v, out) {
60
+ if (v.userAgent !== undefined && !USER_AGENT_MODES.includes(v.userAgent)) {
61
+ out.push('userAgent must be "coherent": turno builds the user agent from the installed Chrome and never takes a typed one, which would contradict the client hints, WebGL, fonts and TLS');
62
+ }
63
+ if (v.proxy === undefined)
64
+ return;
65
+ const p = v.proxy;
66
+ if (!isObject(p)) {
67
+ out.push('proxy must be an object like { "server": "http://proxy.example.com:8080" }');
68
+ return;
69
+ }
70
+ out.push(...serverProblems(p.server));
71
+ // A trace keeps the launch options, the proxy password among them; the recorder would delete
72
+ // every trace, so the pair is refused up front instead.
73
+ if (p.password !== undefined && isObject(v.record) && v.record.traces === true)
74
+ out.push("record.traces does not go with a proxy password: a trace keeps the browser's launch options, the password included. Record flows and screenshots, or use a proxy without a password");
75
+ if (p.username !== undefined && (typeof p.username !== "string" || !p.username.trim() || /[\r\n]/.test(p.username)))
76
+ out.push("proxy.username must be a user name or a keychain:<item> reference");
77
+ if (p.password !== undefined) {
78
+ if (typeof p.password !== "string" || !p.password.startsWith(KEYCHAIN) || p.password.length <= KEYCHAIN.length)
79
+ out.push("proxy.password must be a keychain:<item> reference (store it with: turno secret set <item>): identity.json never holds a password");
80
+ }
81
+ if (p.password !== undefined && p.username === undefined)
82
+ out.push("proxy.password needs proxy.username");
83
+ if (p.username !== undefined && p.password === undefined)
84
+ out.push("proxy.username needs proxy.password (a keychain:<item> reference)");
85
+ if (p.username !== undefined &&
86
+ typeof p.server === "string" &&
87
+ /^socks[45]:/.test(p.server) &&
88
+ !serverProblems(p.server).length)
89
+ out.push("Chrome cannot sign in to a SOCKS proxy: use an http:// or https:// proxy for one that needs a password");
90
+ for (const k of Object.keys(p))
91
+ if (!["server", "username", "password"].includes(k))
92
+ out.push(`unknown key "proxy.${k}"`);
93
+ }
94
+ /**
95
+ * Why an engine cannot apply these settings. Attach mode drives the user's own Chrome, whose
96
+ * user agent and network turno does not change; read mode is Lightpanda, which presents its
97
+ * own user agent and was not checked with a proxy; Camoufox is Firefox, which sends no client
98
+ * hints at all, so `userAgent` describes nothing there (a proxy works).
99
+ */
100
+ export function networkEngineClash(engine, settings) {
101
+ const asked = [settings.userAgent !== undefined && "userAgent", settings.proxy !== undefined && "proxy"].filter(Boolean);
102
+ if (!asked.length)
103
+ return undefined;
104
+ if (engine === "attach")
105
+ return `${asked.join(" and ")} ${asked.length > 1 ? "do" : "does"} not go with attach mode: that is your own Chrome, and turno does not change its user agent or network. Drop ${asked.length > 1 ? "them" : "it"}, or drop attach`;
106
+ if (engine === "lightpanda")
107
+ return `${asked.join(" and ")} ${asked.length > 1 ? "do" : "does"} not go with engine "lightpanda": read mode presents Lightpanda's own user agent and was not checked with a proxy. Use engine "chrome"`;
108
+ if (engine === "camoufox" && settings.userAgent !== undefined)
109
+ return 'userAgent does not go with engine "camoufox": Camoufox is Firefox, which sends no client hints, and it presents its own values. Drop userAgent (proxy works with Camoufox)';
110
+ return undefined;
111
+ }
112
+ /**
113
+ * Reads the proxy's credentials from the secret store. Every value read is handed to `secret`
114
+ * (the redactor) before anything else sees it, with the `Proxy-Authorization` form Chrome sends
115
+ * for a plain http:// request through the proxy. Throws without the value when an item is
116
+ * missing or the store cannot be read.
117
+ */
118
+ export async function resolveProxy(proxy, env, secret, store = secretStore(env)) {
119
+ const out = { server: proxy.server };
120
+ if (proxy.username === undefined || proxy.password === undefined)
121
+ return out;
122
+ const read = async (ref, what) => {
123
+ if (!ref.startsWith(KEYCHAIN))
124
+ return ref;
125
+ const item = ref.slice(KEYCHAIN.length);
126
+ if (!store)
127
+ throw new Error(`the proxy ${what} is ${ref}, but this machine has no secret store (macOS Keychain or libsecret)`);
128
+ let value;
129
+ try {
130
+ value = await store.get(item);
131
+ }
132
+ catch {
133
+ throw new Error(`the secret store could not read the proxy ${what} (${ref})`);
134
+ }
135
+ if (value === undefined || value === "")
136
+ throw new Error(`the secret store has no item "${item}" for the proxy ${what} (store it with: turno secret set ${item})`);
137
+ return value;
138
+ };
139
+ const username = await read(proxy.username, "user name");
140
+ const password = await read(proxy.password, "password");
141
+ if (proxy.username.startsWith(KEYCHAIN))
142
+ secret(username, "proxy user name");
143
+ secret(password, "proxy password");
144
+ const basic = Buffer.from(`${username}:${password}`).toString("base64");
145
+ // "password" in the label: a saved trace holding it is deleted (recordings.ts).
146
+ secret(basic, "proxy password, Basic encoded");
147
+ return { ...out, username, password };
148
+ }
149
+ /**
150
+ * Chrome switches that go with a proxy: WebRTC uses the proxy or no UDP at all, so a page
151
+ * cannot read the direct address through a peer connection.
152
+ */
153
+ export const CHROME_PROXY_ARGS = Object.freeze([
154
+ "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
155
+ ]);
156
+ /** The same for Firefox (Camoufox): ICE candidates only through the proxy. */
157
+ export const FIREFOX_PROXY_PREFS = Object.freeze({
158
+ "media.peerconnection.ice.proxy_only_if_behind_proxy": true,
159
+ "media.peerconnection.ice.default_address_only": true,
160
+ });
161
+ /** The OS tokens of Chrome's reduced user agent string, frozen by Chrome for every version of each OS. */
162
+ const UA_PLATFORM = {
163
+ darwin: "Macintosh; Intel Mac OS X 10_15_7",
164
+ win32: "Windows NT 10.0; Win64; x64",
165
+ linux: "X11; Linux x86_64",
166
+ };
167
+ /**
168
+ * Chrome's own reduced user agent string for this OS and major version, as a headed Chrome
169
+ * sends it (the minor, build and patch are always 0 there).
170
+ */
171
+ export function reducedUserAgent(major, platform = process.platform) {
172
+ const os = UA_PLATFORM[platform] ?? UA_PLATFORM.linux;
173
+ return `Mozilla/5.0 (${os}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
174
+ }
175
+ /** The `navigator.userAgentData.platform` and `navigator.platform` prefixes for each UA OS token. */
176
+ const PLATFORMS = [
177
+ { ua: /Macintosh/, hints: "macOS", navigator: /^Mac/ },
178
+ { ua: /Windows/, hints: "Windows", navigator: /^Win/ },
179
+ { ua: /CrOS/, hints: "Chrome OS", navigator: /^Linux/ },
180
+ { ua: /Android/, hints: "Android", navigator: /^Linux/ },
181
+ { ua: /X11|Linux/, hints: "Linux", navigator: /^Linux/ },
182
+ ];
183
+ const base = (tag) => tag.split("-")[0].toLowerCase();
184
+ const highEntropyKey = (h) => JSON.stringify([h.fullVersionList.map((b) => `${b.brand} ${b.version}`), h.architecture, h.platformVersion]);
185
+ /**
186
+ * Every contradiction between what a page reads and what the identity presents; empty when
187
+ * the set is coherent. Pure, so the bench and the unit tests use it too.
188
+ */
189
+ export function coherenceProblems(o, expected = {}) {
190
+ const out = [];
191
+ if (/HeadlessChrome/.test(o.userAgent))
192
+ out.push("the user agent says HeadlessChrome");
193
+ const major = /Chrome\/(\d+)\./.exec(o.userAgent)?.[1];
194
+ if (!major)
195
+ out.push("the user agent has no Chrome version");
196
+ if (!o.uaData)
197
+ out.push("navigator.userAgentData is missing");
198
+ else {
199
+ if (major && !o.uaData.brands.some((b) => /^(Google Chrome|Chromium)$/.test(b.brand) && b.version === major))
200
+ out.push(`the client hints brands (${o.uaData.brands.map((b) => `${b.brand} ${b.version}`).join(", ")}) do not name Chrome ${major}`);
201
+ const os = PLATFORMS.find((p) => p.ua.test(o.userAgent));
202
+ if (os && o.uaData.platform !== os.hints)
203
+ out.push(`the user agent is ${os.hints} but the client hints platform is ${o.uaData.platform}`);
204
+ if (os && !os.navigator.test(o.platform))
205
+ out.push(`the user agent is ${os.hints} but navigator.platform is ${o.platform}`);
206
+ if (o.uaData.mobile)
207
+ out.push("the client hints say mobile");
208
+ const high = o.uaData.high;
209
+ // Chrome on Linux reports an empty platform version, as a person's Chrome there does.
210
+ const versionless = o.uaData.platform === "Linux";
211
+ if (high && (!high.fullVersionList.length || !high.architecture || (!high.platformVersion && !versionless)))
212
+ out.push("the client hints high entropy values (full version list, architecture, platform version) are blank");
213
+ else if (high && expected.high && highEntropyKey(high) !== highEntropyKey(expected.high))
214
+ out.push(`the client hints high entropy values (${high.architecture || "no architecture"}, platform version ${high.platformVersion || "empty"}) differ from this Chrome's own (${expected.high.architecture}, platform version ${expected.high.platformVersion || "empty"})`);
215
+ else if (high &&
216
+ major &&
217
+ !high.fullVersionList.some((b) => /^(Google Chrome|Chromium)$/.test(b.brand) && majorOf(b.version) === Number(major)))
218
+ out.push(`the client hints full version list does not name Chrome ${major}`);
219
+ }
220
+ if (expected.languages?.length) {
221
+ if (JSON.stringify(o.languages) !== JSON.stringify(expected.languages))
222
+ out.push(`navigator.languages is ${o.languages.join(", ")}, not ${expected.languages.join(", ")}`);
223
+ }
224
+ const first = expected.languages?.[0] ?? o.languages[0];
225
+ if (first && base(o.intlLocale) !== base(first))
226
+ out.push(`dates and numbers are formatted in ${o.intlLocale}, but the first language is ${first}` +
227
+ (process.platform === "darwin"
228
+ ? " (on macOS Chrome takes that from the system language, not from flags: set languages to start with it, or change the macOS language)"
229
+ : ""));
230
+ if (expected.timezone && o.timezone !== expected.timezone)
231
+ out.push(`the time zone is ${o.timezone}, not ${expected.timezone}`);
232
+ return out;
233
+ }
234
+ /** Runs in a page: what `coherenceProblems` checks. */
235
+ export const OBSERVE_SCRIPT = `async () => {
236
+ const d = navigator.userAgentData;
237
+ const high = d ? await d.getHighEntropyValues(["fullVersionList", "architecture", "platformVersion"]) : null;
238
+ return {
239
+ userAgent: navigator.userAgent,
240
+ platform: navigator.platform,
241
+ languages: Array.from(navigator.languages || []),
242
+ timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
243
+ intlLocale: Intl.DateTimeFormat().resolvedOptions().locale,
244
+ uaData: d
245
+ ? {
246
+ brands: d.brands.map((b) => ({ brand: b.brand, version: b.version })),
247
+ platform: d.platform,
248
+ mobile: d.mobile,
249
+ high: {
250
+ fullVersionList: (high.fullVersionList || []).map((b) => ({ brand: b.brand, version: b.version })),
251
+ architecture: high.architecture || "",
252
+ platformVersion: high.platformVersion || "",
253
+ },
254
+ }
255
+ : null,
256
+ };
257
+ }`;
258
+ /** The installed Chrome's major version from a version string like "157.0.8103.79". */
259
+ export function majorOf(version) {
260
+ const m = /^(\d+)\./.exec(version ?? "");
261
+ return m ? Number(m[1]) : undefined;
262
+ }
263
+ //# sourceMappingURL=network.js.map
@@ -0,0 +1,69 @@
1
+ /**
2
+ * The format 8 keys of identity.json: natural language actions (`act`) and captcha solving
3
+ * (`captcha`). Both are off until the key is there, and both send page content to a third
4
+ * party the user picks, so neither has a default provider:
5
+ *
6
+ * "act": {
7
+ * "sampling": true, // ask the agent's own client (MCP sampling) first
8
+ * "provider": "chat-completions", // else this HTTP API
9
+ * "endpoint": "https://models.example.com/v1",
10
+ * "model": "example-model",
11
+ * "key": "keychain:act-model", // optional; a reference, never the key
12
+ * "maxSteps": 10, "maxTokens": 50000, "timeout": "2m"
13
+ * },
14
+ * "captcha": {
15
+ * "provider": "task-api",
16
+ * "endpoint": "https://solver.example.com",
17
+ * "key": "keychain:captcha-solver",
18
+ * "timeout": "3m"
19
+ * }
20
+ *
21
+ * A key is read from the secret store at use time (turno-core), never from a tool argument and
22
+ * never written here: a value that is not a `keychain:` reference is refused, and the message
23
+ * does not repeat it.
24
+ */
25
+ /** The model providers `act` can name besides MCP sampling. */
26
+ declare const ACT_PROVIDERS: readonly ["chat-completions"];
27
+ /** The captcha solver protocols `captcha` can name. */
28
+ declare const CAPTCHA_PROVIDERS: readonly ["task-api"];
29
+ export interface ActSettings {
30
+ /** Use MCP sampling when the client offers it (default true). */
31
+ sampling?: boolean;
32
+ provider?: (typeof ACT_PROVIDERS)[number];
33
+ /** Base URL of the provider's API: https, or http on a loopback address. */
34
+ endpoint?: string;
35
+ model?: string;
36
+ /** `keychain:<item>`: the API key, read from the secret store. */
37
+ key?: string;
38
+ /** Most actions one `browser_act` call takes (default 10, at most 30). */
39
+ maxSteps?: number;
40
+ /** Most model tokens one call spends, prompts and replies together (default 50000). */
41
+ maxTokens?: number;
42
+ /** Longest one call runs, like `"2m"` (default 2m, from 10s to 10m). */
43
+ timeout?: string;
44
+ }
45
+ export interface CaptchaSettings {
46
+ provider: (typeof CAPTCHA_PROVIDERS)[number];
47
+ endpoint: string;
48
+ /** `keychain:<item>`: the solver's account key, read from the secret store. */
49
+ key: string;
50
+ /** Longest one solve waits, like `"3m"` (default 3m, from 10s to 10m). */
51
+ timeout?: string;
52
+ }
53
+ /** Budgets of one natural language call, after the defaults. */
54
+ export interface ActBudget {
55
+ maxSteps: number;
56
+ maxTokens: number;
57
+ timeoutMs: number;
58
+ }
59
+ /** True for https, or http on a loopback host (a model server on this machine). */
60
+ export declare function allowedEndpoint(value: string): boolean;
61
+ /** Problems with `act`, in key order. */
62
+ export declare function actProblems(a: unknown, out: string[]): void;
63
+ /** Problems with `captcha`, alone and with the engine keys. */
64
+ export declare function captchaProblems(c: unknown, settings: Record<string, unknown>, out: string[]): void;
65
+ /** The budgets of an `act` group, defaults filled in. */
66
+ export declare function actBudget(a: ActSettings): ActBudget;
67
+ /** How long one captcha solve may wait. */
68
+ export declare function captchaTimeoutMs(c: CaptchaSettings): number;
69
+ export {};
@@ -0,0 +1,151 @@
1
+ import { parseDuration } from "./units.js";
2
+ /**
3
+ * The format 8 keys of identity.json: natural language actions (`act`) and captcha solving
4
+ * (`captcha`). Both are off until the key is there, and both send page content to a third
5
+ * party the user picks, so neither has a default provider:
6
+ *
7
+ * "act": {
8
+ * "sampling": true, // ask the agent's own client (MCP sampling) first
9
+ * "provider": "chat-completions", // else this HTTP API
10
+ * "endpoint": "https://models.example.com/v1",
11
+ * "model": "example-model",
12
+ * "key": "keychain:act-model", // optional; a reference, never the key
13
+ * "maxSteps": 10, "maxTokens": 50000, "timeout": "2m"
14
+ * },
15
+ * "captcha": {
16
+ * "provider": "task-api",
17
+ * "endpoint": "https://solver.example.com",
18
+ * "key": "keychain:captcha-solver",
19
+ * "timeout": "3m"
20
+ * }
21
+ *
22
+ * A key is read from the secret store at use time (turno-core), never from a tool argument and
23
+ * never written here: a value that is not a `keychain:` reference is refused, and the message
24
+ * does not repeat it.
25
+ */
26
+ /** The model providers `act` can name besides MCP sampling. */
27
+ const ACT_PROVIDERS = ["chat-completions"];
28
+ /** The captcha solver protocols `captcha` can name. */
29
+ const CAPTCHA_PROVIDERS = ["task-api"];
30
+ const ACT_DEFAULTS = { maxSteps: 10, maxTokens: 50_000, timeoutMs: 120_000 };
31
+ const MAX_STEPS = 30;
32
+ const MIN_TOKENS = 2_000;
33
+ const MAX_TOKENS = 1_000_000;
34
+ const MIN_TIMEOUT_MS = 10_000;
35
+ const MAX_TIMEOUT_MS = 600_000;
36
+ const CAPTCHA_DEFAULT_TIMEOUT_MS = 180_000;
37
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
38
+ /** True for https, or http on a loopback host (a model server on this machine). */
39
+ export function allowedEndpoint(value) {
40
+ let url;
41
+ try {
42
+ url = new URL(value);
43
+ }
44
+ catch {
45
+ return false;
46
+ }
47
+ if (url.username || url.password)
48
+ return false;
49
+ if (url.protocol === "https:")
50
+ return true;
51
+ return url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
52
+ }
53
+ const KEYCHAIN = /^keychain:[A-Za-z0-9._\-/]{1,200}$/;
54
+ /** True for a `keychain:<item>` reference. */
55
+ function isKeychainRef(value) {
56
+ return typeof value === "string" && KEYCHAIN.test(value);
57
+ }
58
+ function timeoutProblem(key, v, out) {
59
+ if (v === undefined)
60
+ return;
61
+ const ms = typeof v === "string" ? parseDuration(v) : undefined;
62
+ if (ms === undefined || ms < MIN_TIMEOUT_MS || ms > MAX_TIMEOUT_MS)
63
+ out.push(`${key} must be a duration from "10s" to "10m", like "2m"`);
64
+ }
65
+ function keyProblem(key, v, out, required) {
66
+ if (v === undefined) {
67
+ if (required)
68
+ out.push(`${key} is required: a keychain:<item> reference (turno secret set <item>)`);
69
+ return;
70
+ }
71
+ // Never echo the value: a pasted key would land in a terminal or a log.
72
+ if (!isKeychainRef(v))
73
+ out.push(`${key} must be a keychain:<item> reference (store the key with turno secret set <item>), never the key itself`);
74
+ }
75
+ function endpointProblem(key, v, out) {
76
+ if (typeof v !== "string" || !allowedEndpoint(v))
77
+ out.push(`${key} must be an https:// URL (or http:// on 127.0.0.1, localhost or [::1]) without a user or password`);
78
+ }
79
+ /** Problems with `act`, in key order. */
80
+ export function actProblems(a, out) {
81
+ if (a === undefined)
82
+ return;
83
+ if (!isObject(a)) {
84
+ out.push('act must be an object, like {} (MCP sampling) or { "provider": "chat-completions", ... }');
85
+ return;
86
+ }
87
+ if (a.sampling !== undefined && typeof a.sampling !== "boolean")
88
+ out.push("act.sampling must be true or false");
89
+ if (a.provider !== undefined) {
90
+ if (!ACT_PROVIDERS.includes(a.provider))
91
+ out.push(`act.provider must be ${ACT_PROVIDERS.map((p) => `"${p}"`).join(", ")}`);
92
+ endpointProblem("act.endpoint", a.endpoint, out);
93
+ if (typeof a.model !== "string" || !a.model.trim() || a.model.length > 200)
94
+ out.push("act.model must be the model name the provider expects");
95
+ keyProblem("act.key", a.key, out, false);
96
+ }
97
+ else {
98
+ for (const k of ["endpoint", "model", "key"])
99
+ if (a[k] !== undefined)
100
+ out.push(`act.${k} needs act.provider`);
101
+ if (a.sampling === false)
102
+ out.push("act needs act.provider when act.sampling is false: nothing would answer");
103
+ }
104
+ if (a.maxSteps !== undefined &&
105
+ (typeof a.maxSteps !== "number" || !Number.isInteger(a.maxSteps) || a.maxSteps < 1 || a.maxSteps > MAX_STEPS))
106
+ out.push(`act.maxSteps must be a whole number from 1 to ${MAX_STEPS}`);
107
+ if (a.maxTokens !== undefined &&
108
+ (typeof a.maxTokens !== "number" ||
109
+ !Number.isInteger(a.maxTokens) ||
110
+ a.maxTokens < MIN_TOKENS ||
111
+ a.maxTokens > MAX_TOKENS))
112
+ out.push(`act.maxTokens must be a whole number from ${MIN_TOKENS} to ${MAX_TOKENS}`);
113
+ timeoutProblem("act.timeout", a.timeout, out);
114
+ for (const k of Object.keys(a))
115
+ if (!["sampling", "provider", "endpoint", "model", "key", "maxSteps", "maxTokens", "timeout"].includes(k))
116
+ out.push(`unknown key "act.${k}"`);
117
+ }
118
+ /** Problems with `captcha`, alone and with the engine keys. */
119
+ export function captchaProblems(c, settings, out) {
120
+ if (c === undefined)
121
+ return;
122
+ if (!isObject(c)) {
123
+ out.push('captcha must be an object with provider, endpoint and key, like { "provider": "task-api", ... }');
124
+ return;
125
+ }
126
+ if (!CAPTCHA_PROVIDERS.includes(c.provider))
127
+ out.push(`captcha.provider must be ${CAPTCHA_PROVIDERS.map((p) => `"${p}"`).join(", ")}`);
128
+ endpointProblem("captcha.endpoint", c.endpoint, out);
129
+ keyProblem("captcha.key", c.key, out, true);
130
+ timeoutProblem("captcha.timeout", c.timeout, out);
131
+ for (const k of Object.keys(c))
132
+ if (!["provider", "endpoint", "key", "timeout"].includes(k))
133
+ out.push(`unknown key "captcha.${k}"`);
134
+ if (settings.engine === "lightpanda")
135
+ out.push('captcha does not go with engine "lightpanda": read mode runs no captcha widget to solve');
136
+ if (settings.engine === "camoufox")
137
+ out.push("captcha does not go with engine \"camoufox\": the token is set from Patchright's isolated script world and the widget's callback from the page's own, and Camoufox runs on stock Playwright");
138
+ }
139
+ /** The budgets of an `act` group, defaults filled in. */
140
+ export function actBudget(a) {
141
+ return {
142
+ maxSteps: a.maxSteps ?? ACT_DEFAULTS.maxSteps,
143
+ maxTokens: a.maxTokens ?? ACT_DEFAULTS.maxTokens,
144
+ timeoutMs: (a.timeout !== undefined ? parseDuration(a.timeout) : undefined) ?? ACT_DEFAULTS.timeoutMs,
145
+ };
146
+ }
147
+ /** How long one captcha solve may wait. */
148
+ export function captchaTimeoutMs(c) {
149
+ return (c.timeout !== undefined ? parseDuration(c.timeout) : undefined) ?? CAPTCHA_DEFAULT_TIMEOUT_MS;
150
+ }
151
+ //# sourceMappingURL=opt-in-settings.js.map
@@ -1,6 +1,8 @@
1
1
  /**
2
- * The Playwright MCP program shipped inside patchright-core (ADR 0003). The subpath is not in
3
- * the package `exports`, so it is resolved from the install dir.
2
+ * The Playwright MCP program shipped inside patchright-core. The subpath is not in
3
+ * the package `exports`, so it is resolved from the install dir. `turno-browser-mcp` no longer
4
+ * runs it (turno's host serves the same tools); the contract test still starts it
5
+ * to compare tool lists.
4
6
  */
5
7
  export declare function mcpEntryPath(): string;
6
8
  export declare function resolveFrom(name: string): string | undefined;
@@ -6,8 +6,10 @@ function patchrightDir() {
6
6
  return dirname(require.resolve("patchright-core/package.json"));
7
7
  }
8
8
  /**
9
- * The Playwright MCP program shipped inside patchright-core (ADR 0003). The subpath is not in
10
- * the package `exports`, so it is resolved from the install dir.
9
+ * The Playwright MCP program shipped inside patchright-core. The subpath is not in
10
+ * the package `exports`, so it is resolved from the install dir. `turno-browser-mcp` no longer
11
+ * runs it (turno's host serves the same tools); the contract test still starts it
12
+ * to compare tool lists.
11
13
  */
12
14
  export function mcpEntryPath() {
13
15
  return join(patchrightDir(), "lib", "entry", "mcp.js");
@@ -0,0 +1,88 @@
1
+ import type { Page } from "patchright-core";
2
+ import type { IdentityRef } from "./engine.js";
3
+ import { type Flow, type FlowStep } from "./flows.js";
4
+ import type { Redactor } from "./redact.js";
5
+ import type { TurnoTool } from "./tools.js";
6
+ /** What the page says about an element, for its locators and to tell a secret field. */
7
+ interface ElementInfo {
8
+ tag: string;
9
+ type: string;
10
+ autocomplete: string;
11
+ name: string;
12
+ id: string;
13
+ text: string;
14
+ css: string;
15
+ }
16
+ export declare const SECRET_AUTOCOMPLETE: RegExp;
17
+ export declare const SECRET_NAME: RegExp;
18
+ /** A field whose typed value must never be stored. */
19
+ export declare function secretField(info: Pick<ElementInfo, "type" | "autocomplete" | "name" | "id">): boolean;
20
+ /**
21
+ * The values a `browser_type` or `browser_fill_form` call is about to put into secret fields
22
+ * (`secretField`), so a recording can stop its trace first. A target the page cannot resolve
23
+ * counts as not secret: the call then fails the same way.
24
+ */
25
+ export declare function secretValues(page: Page, tool: string, args: Record<string, unknown>): Promise<string[]>;
26
+ /**
27
+ * Role and accessible name from Playwright's generated locator when it is a role locator
28
+ * (`internal:role=button[name="Sign in"i]`). Asking the element for its aria snapshot instead
29
+ * would renumber the page's refs and break the call the agent is making.
30
+ */
31
+ export declare function roleFromSelector(selector: string): {
32
+ role: string;
33
+ name?: string;
34
+ } | undefined;
35
+ /** A typed value of a step, before each draft gives it a parameter name. */
36
+ export interface Slot {
37
+ path: string;
38
+ value: string;
39
+ sensitive: boolean;
40
+ label?: string;
41
+ description?: string;
42
+ }
43
+ /** A step captured before its tool ran; committed only when the tool worked. */
44
+ export interface PendingStep {
45
+ step: FlowStep;
46
+ slots: Slot[];
47
+ }
48
+ /** The recorder of one MCP session. */
49
+ export declare class FlowRecorder {
50
+ private readonly identity;
51
+ private readonly redactor;
52
+ /** identity.json `record.flows`: record every session as `auto-<time>`. */
53
+ private readonly autoFlows;
54
+ private named;
55
+ private overwrite;
56
+ private auto;
57
+ private suspended;
58
+ constructor(identity: IdentityRef, redactor: Redactor,
59
+ /** identity.json `record.flows`: record every session as `auto-<time>`. */
60
+ autoFlows: () => boolean);
61
+ /** True when a step would be kept now. */
62
+ get active(): boolean;
63
+ get recording(): {
64
+ name: string;
65
+ steps: number;
66
+ params: number;
67
+ full: boolean;
68
+ } | undefined;
69
+ start(name: string, description: string | undefined, overwrite: boolean): void;
70
+ /** Saves the named flow, with `sensitive` parameters' values dropped. */
71
+ stop(sensitive?: readonly string[], description?: string): {
72
+ flow: Flow;
73
+ file: string;
74
+ };
75
+ cancel(): boolean;
76
+ /** Runs `fn` without recording its steps (a replay is recorded as one step). */
77
+ suspend<T>(fn: () => Promise<T>): Promise<T>;
78
+ /** A stock tool call about to run, as a step; undefined when it is not one a flow keeps. */
79
+ capture(tool: string, args: Record<string, unknown>, page: Page | undefined): Promise<PendingStep | undefined>;
80
+ /** Keeps a captured step after its tool worked. */
81
+ commit(pending: PendingStep): void;
82
+ /** A turno tool as a step: `browser_login` (site only) or `browser_replay` (its flow and parameters). */
83
+ record(tool: "browser_login" | "browser_replay", args: Record<string, unknown>, slots?: Slot[]): void;
84
+ private commitAuto;
85
+ }
86
+ /** `browser_record`. */
87
+ export declare function recordTool(): TurnoTool;
88
+ export {};