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/engine.js ADDED
@@ -0,0 +1,355 @@
1
+ import { resolve } from "node:path";
2
+ import { storagePartitioningArgs } from "./chrome-features.js";
3
+ import { createAttachEngine, parseAttachTarget } from "./engine-attach.js";
4
+ import { createCamoufoxEngine } from "./engine-camoufox.js";
5
+ import { createLightpandaEngine } from "./engine-lightpanda.js";
6
+ import { findProfileChrome, readLockPid } from "./lifecycle.js";
7
+ import { chromeNetwork, pinUserAgent, verifyCoherence } from "./network-chrome.js";
8
+ import { networkEngineClash } from "./network.js";
9
+ import { acquireRuntimeLock } from "./runtime-lock.js";
10
+ import { keychainArgs, launchSettings, readIdentitySettings, recordEngineClash, systemTimezone, } from "./settings.js";
11
+ import { launchTuning } from "./tuning.js";
12
+ import { IdleTimer, idleMs } from "./idle-timer.js";
13
+ import { playwright, upstream } from "./upstream.js";
14
+ /** True when the config asks for the browser the `chrome` engine launches. */
15
+ export function usesChromeEngine(config) {
16
+ const b = config.browser;
17
+ return (b.browserName === "chromium" &&
18
+ b.userDataDir !== undefined &&
19
+ !b.isolated &&
20
+ !b.cdpEndpoint &&
21
+ !b.remoteEndpoint &&
22
+ !config.extension &&
23
+ !config.sharedBrowserContext);
24
+ }
25
+ async function profileLocked5Times(userDataDir) {
26
+ const { tools } = upstream();
27
+ for (let i = 0; i < 5; i++) {
28
+ if (!tools.isProfileLocked(userDataDir))
29
+ return false;
30
+ await new Promise((r) => setTimeout(r, 1000));
31
+ }
32
+ return true;
33
+ }
34
+ /** Upstream's launch errors, word for word, so a user sees the same message as before. */
35
+ function launchError(error, config, userDataDir, channel) {
36
+ const message = error.message;
37
+ if (message.includes("Executable doesn't exist")) {
38
+ const target = message.includes("ffmpeg")
39
+ ? "ffmpeg"
40
+ : (config.browser.launchOptions.channel ?? config.browser.browserName);
41
+ const label = target === "ffmpeg" ? "FFmpeg" : `Browser "${target}"`;
42
+ const command = config.skillMode
43
+ ? `playwright-cli install-browser ${target}`
44
+ : `npx @playwright/mcp install-browser ${target}`;
45
+ const match = message.match(/Executable doesn't exist at ([^\r\n]+)/);
46
+ const location = match ? `; expected executable at ${match[1].trim()}` : "";
47
+ return new Error(`${label} is not installed${location}. Run \`${command}\` to install`);
48
+ }
49
+ if (message.includes("cannot open shared object file: No such file or directory")) {
50
+ const name = channel ?? config.browser.browserName;
51
+ return new Error(`Missing system dependencies required to run browser ${name}. Install them with: sudo npx playwright install-deps ${name}`);
52
+ }
53
+ if (message.includes("ProcessSingleton") || message.includes("exitCode=21")) {
54
+ return new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
55
+ }
56
+ return error;
57
+ }
58
+ /** For an identity, who holds the profile instead of upstream's generic "already in use". */
59
+ function profileInUse(identity, userDataDir) {
60
+ if (!identity)
61
+ return new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
62
+ const chrome = findProfileChrome(userDataDir);
63
+ const who = chrome ? `a Chrome that turno-browser-mcp did not start (pid ${chrome.pid})` : "another Chrome";
64
+ return new Error(`browser identity "${identity.id}" is in use by ${who}: a Chrome opened by hand on this profile, or a login from an older turno. ` +
65
+ `Close it, then try again; \`turno browser doctor\` shows who holds each identity.`);
66
+ }
67
+ /**
68
+ * The installed Chrome on a persistent profile, launched by turno with the options upstream's
69
+ * `createPersistentBrowser` uses: the resolved launch and context options, no signal handlers
70
+ * of Playwright's own (the host's shutdown guard and upstream's exit watchdog close it), and
71
+ * extensions allowed. It is bound like upstream's browser, so `playwright-cli` sees it too.
72
+ *
73
+ * For an identity it also takes the identity's runtime lock before Chrome starts,
74
+ * records Chrome's PID and process group in it, gives it back when Chrome closes, and applies
75
+ * identity.json: languages and locale as Chrome flags, the time zone as `timezoneId`. With
76
+ * `backgroundThrottling` it drops Playwright's three anti-throttling switches and
77
+ * turns off its focus emulation (`launchTuning`). Third-party storage partitioning, which
78
+ * Playwright turns off, stays on (`chrome-features.ts`).
79
+ */
80
+ const chromeEngine = {
81
+ id: "chrome",
82
+ async launch({ config, clientInfo, title, identity, tuning, secret }) {
83
+ const userDataDir = config.browser.userDataDir;
84
+ if (userDataDir === undefined)
85
+ throw new Error("the chrome engine needs a profile directory");
86
+ const { tools } = upstream();
87
+ const tracesDir = resolve(tools.outputDir({ config, cwd: clientInfo.cwd }), "traces");
88
+ const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
89
+ // Proxy credentials and the coherent user agent are settled before the lock: a missing
90
+ // secret or an unknown Chrome version stops here, with nothing to undo.
91
+ const network = settings ? await chromeNetwork(settings, config, identity.env, secret ?? (() => { })) : undefined;
92
+ const held = identity ? acquireRuntimeLock(identity.id, identity.env, { holder: "mcp" }) : undefined;
93
+ let context;
94
+ let browser;
95
+ try {
96
+ if (await profileLocked5Times(userDataDir))
97
+ throw profileInUse(identity, userDataDir);
98
+ const ignore = config.browser.launchOptions.ignoreDefaultArgs;
99
+ const userArgs = config.browser.launchOptions.args ?? [];
100
+ const applied = launchSettings(settings, userArgs, systemTimezone(), config.browser.contextOptions);
101
+ const tuned = tuning ? launchTuning(tuning) : { ignoreDefaultArgs: [], contextOptions: {} };
102
+ // Chrome's third-party storage partitioning stays on, as in a person's Chrome (`chrome-features.ts`).
103
+ const partitioning = config.browser.browserName === "chromium" && ignore !== true ? storagePartitioningArgs() : undefined;
104
+ const launchOptions = {
105
+ tracesDir,
106
+ ...config.browser.launchOptions,
107
+ ...tuned.contextOptions,
108
+ ...config.browser.contextOptions,
109
+ args: [...(partitioning?.args ?? []), ...userArgs, ...applied.args, ...(network?.args ?? [])],
110
+ ...(applied.timezoneId ? { timezoneId: applied.timezoneId } : {}),
111
+ ...(network?.proxy ? { proxy: network.proxy } : {}),
112
+ handleSIGINT: false,
113
+ handleSIGTERM: false,
114
+ ignoreDefaultArgs: ignore === true
115
+ ? true
116
+ : [
117
+ "--disable-extensions",
118
+ ...(partitioning?.ignoreDefaultArgs ?? []),
119
+ ...tuned.ignoreDefaultArgs,
120
+ ...(keychainArgs(settings).ignoreDefaultArgs ?? []),
121
+ ...(Array.isArray(ignore) ? ignore : []),
122
+ ],
123
+ };
124
+ try {
125
+ context = await playwright()[config.browser.browserName].launchPersistentContext(userDataDir, launchOptions);
126
+ }
127
+ catch (err) {
128
+ throw launchError(err, config, userDataDir, launchOptions.channel);
129
+ }
130
+ browser = context.browser();
131
+ try {
132
+ const pinned = network?.pin ? pinUserAgent(context, network.pin) : undefined;
133
+ if (network?.verify)
134
+ await verifyCoherence(context, browser.version(), network.verify, pinned);
135
+ await browser.bind(title, { workspaceDir: clientInfo.cwd });
136
+ }
137
+ catch (err) {
138
+ await browser.close().catch(() => { });
139
+ throw err;
140
+ }
141
+ }
142
+ catch (err) {
143
+ held?.release();
144
+ throw err;
145
+ }
146
+ let closing = false;
147
+ const ms = idleMs(config);
148
+ let idleTimer;
149
+ if (ms) {
150
+ const timer = new IdleTimer(ms, () => {
151
+ closing = true;
152
+ void browser.close().catch(() => { });
153
+ });
154
+ browser.once("disconnected", () => timer.dispose());
155
+ idleTimer = timer;
156
+ }
157
+ const pid = readLockPid(userDataDir);
158
+ if (held) {
159
+ // Playwright starts Chrome as the leader of its own process group; ps confirms it.
160
+ const pgid = pid !== undefined ? (findProfileChrome(userDataDir)?.pgid ?? pid) : undefined;
161
+ held.update({ ...(pid !== undefined ? { chromePid: pid } : {}), ...(pgid !== undefined ? { pgid } : {}) });
162
+ browser.once("disconnected", () => held.release());
163
+ }
164
+ return {
165
+ engine: "chrome",
166
+ context,
167
+ ...(pid !== undefined ? { pid } : {}),
168
+ ...(idleTimer ? { idleTimer } : {}),
169
+ isOpen: () => !closing && browser.isConnected(),
170
+ async close() {
171
+ closing = true;
172
+ idleTimer?.dispose();
173
+ await context.close().catch(() => { });
174
+ await browser.close().catch(() => { });
175
+ held?.release();
176
+ },
177
+ };
178
+ },
179
+ };
180
+ function remoteConnectOptions(config) {
181
+ const remote = config.browser.remoteEndpoint;
182
+ const headers = config.browser.remoteHeaders;
183
+ if (remote === undefined)
184
+ return {};
185
+ if (typeof remote === "string")
186
+ return { headers };
187
+ const { endpoint: _endpoint, ...options } = remote;
188
+ return { ...options, headers: { ...headers, ...remote.headers } };
189
+ }
190
+ /**
191
+ * Every mode turno does not launch itself goes through upstream's `createBrowserWithInfo`,
192
+ * with the session handling of upstream's MCP program (`program.ts`): sessions share one
193
+ * browser for `--shared-browser-context` and `--isolated`, and the last one to leave closes it.
194
+ */
195
+ function createUpstreamEngine() {
196
+ let shared;
197
+ let clients = 0;
198
+ return {
199
+ id: "upstream",
200
+ async launch({ config, clientInfo, cliOptions, title }) {
201
+ const { tools } = upstream();
202
+ const useShared = config.sharedBrowserContext || config.browser.isolated;
203
+ const bind = { title: clientInfo.clientName, workspaceDir: clientInfo.cwd };
204
+ if (useShared && !shared) {
205
+ const promise = tools.createBrowserWithInfo(config, clientInfo, cliOptions, bind).then((info) => {
206
+ info.browser.once("disconnected", () => {
207
+ if (shared === promise)
208
+ shared = undefined;
209
+ });
210
+ return info;
211
+ }, (error) => {
212
+ if (shared === promise)
213
+ shared = undefined;
214
+ throw error;
215
+ });
216
+ shared = promise;
217
+ }
218
+ clients++;
219
+ const sharedPromise = shared;
220
+ let sharedInfo;
221
+ let info;
222
+ let browser;
223
+ try {
224
+ sharedInfo = await sharedPromise;
225
+ if (sharedInfo) {
226
+ info = sharedInfo;
227
+ browser = await sharedInfo.browser.browserType().connect(sharedInfo.endpoint, remoteConnectOptions(config));
228
+ }
229
+ else {
230
+ info = await tools.createBrowserWithInfo(config, clientInfo, cliOptions, { ...bind, title });
231
+ browser = info.browser;
232
+ }
233
+ }
234
+ catch (error) {
235
+ clients--;
236
+ throw error;
237
+ }
238
+ let context;
239
+ try {
240
+ context = config.browser.isolated
241
+ ? await browser.newContext(config.browser.contextOptions)
242
+ : (browser.contexts()[0] ?? (await browser.newContext(config.browser.contextOptions)));
243
+ }
244
+ catch (error) {
245
+ clients--;
246
+ await browser.close().catch(() => { });
247
+ throw error;
248
+ }
249
+ return {
250
+ engine: "upstream",
251
+ context,
252
+ isOpen: () => browser.isConnected(),
253
+ ...(info.idleTimer ? { idleTimer: info.idleTimer } : {}),
254
+ async close() {
255
+ clients--;
256
+ const last = !sharedInfo || !clients;
257
+ if (last && shared === sharedPromise)
258
+ shared = undefined;
259
+ if (!last) {
260
+ if (config.browser.isolated)
261
+ await context.close().catch(() => { });
262
+ await browser.close().catch(() => { });
263
+ return;
264
+ }
265
+ await context.close().catch(() => { });
266
+ await browser.close().catch(() => { });
267
+ await sharedInfo?.browser.close().catch(() => { });
268
+ },
269
+ };
270
+ },
271
+ };
272
+ }
273
+ /** The engine for this config. */
274
+ export function selectEngine(config, fallback) {
275
+ return usesChromeEngine(config) ? chromeEngine : fallback;
276
+ }
277
+ /**
278
+ * Flags first, then identity.json. A flag of either kind replaces both keys of identity.json:
279
+ * `--engine chrome` turns an identity's attach or read mode off for that server.
280
+ */
281
+ export function engineChoice(flags, settings) {
282
+ const fromFlags = flags.engine !== undefined || flags.attach !== undefined;
283
+ const engine = fromFlags ? flags.engine : settings?.engine;
284
+ const attach = fromFlags ? flags.attach : settings?.attach;
285
+ if (attach !== undefined) {
286
+ if (engine === "lightpanda" || engine === "camoufox")
287
+ throw new Error(`attach and the ${engine} engine do not go together: pick one`);
288
+ const target = parseAttachTarget(attach);
289
+ if ("error" in target)
290
+ throw new Error(target.error);
291
+ return { kind: "attach", target };
292
+ }
293
+ if (engine === "lightpanda")
294
+ return { kind: "lightpanda" };
295
+ return engine === "camoufox" ? { kind: "camoufox" } : { kind: "default" };
296
+ }
297
+ /**
298
+ * The host's engine: at every launch it reads the identity's settings and the flags, and hands
299
+ * the launch to `lightpanda`, `attach`, or the engine the config selects.
300
+ */
301
+ /**
302
+ * Why an engine cannot run with these settings, if it cannot: attach mode keeps one agent's tabs
303
+ * apart from the user's, not several sessions apart from each other, and read mode has no
304
+ * layout for human-like input to move over.
305
+ */
306
+ export function tuningClash(engine, tuning) {
307
+ if (engine === "attach" && tuning.sharing === "tabs")
308
+ return '"sharing": "tabs" does not go with attach mode: in your own Chrome turno keeps one agent\'s tabs apart from yours, not several sessions apart. Turn one off (--sharing session, or --attach "")';
309
+ if (engine === "lightpanda" && tuning.humanize.level !== "off")
310
+ return "humanize does not go with read mode: Lightpanda lays out no page, so there is no pointer path or scroll to play. Turn one off (--humanize off, or --engine chrome)";
311
+ return undefined;
312
+ }
313
+ export function createEngine(config, flags = {}, fallback) {
314
+ const base = selectEngine(config, fallback ?? createUpstreamEngine());
315
+ const lightpanda = createLightpandaEngine();
316
+ const camoufox = createCamoufoxEngine();
317
+ const choose = (identity) => {
318
+ const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
319
+ const choice = engineChoice(flags, settings);
320
+ if (choice.kind === "lightpanda")
321
+ return lightpanda;
322
+ if (choice.kind === "camoufox")
323
+ return camoufox;
324
+ if (choice.kind === "attach")
325
+ return createAttachEngine(choice.target);
326
+ return base;
327
+ };
328
+ return {
329
+ id: base.id,
330
+ launch: async (request) => {
331
+ const engine = choose(request.identity);
332
+ const settings = request.identity ? readIdentitySettings(request.identity.id, request.identity.env) : undefined;
333
+ const record = settings?.record;
334
+ // A flag can pick an engine that identity.json's other keys do not go with: refused here,
335
+ // before anything starts.
336
+ const clash = (request.tuning ? tuningClash(engine.id, request.tuning) : undefined) ??
337
+ (record ? recordEngineClash(engine.id, record) : undefined) ??
338
+ (settings ? networkEngineClash(engine.id, settings) : undefined);
339
+ if (clash)
340
+ throw new Error(clash);
341
+ return await engine.launch(request);
342
+ },
343
+ refuse(tool, identity) {
344
+ let engine;
345
+ try {
346
+ engine = choose(identity);
347
+ }
348
+ catch {
349
+ return undefined; // the launch reports a bad identity.json or flag
350
+ }
351
+ return engine.refuse?.(tool, identity);
352
+ },
353
+ };
354
+ }
355
+ //# sourceMappingURL=engine.js.map
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Saved flows: the browser actions a session made on an identity, stored so that
3
+ * `browser_replay` (and `turno browser replay`) can run them again without the model working
4
+ * the page out a second time. One JSON file per flow, under `<data>/browser/flows/<id>/`, next
5
+ * to the identity's other files and never inside its Chrome profile.
6
+ *
7
+ * What a flow file holds, and what it never holds:
8
+ *
9
+ * - Each step names a browser tool and its arguments. An element is kept as several
10
+ * locators (Playwright's own pick, role and accessible name, visible text, a CSS path), tried
11
+ * in that order on replay, plus the snapshot ref it had (for reading only: refs change with
12
+ * every snapshot, so replay never uses one).
13
+ * - Text typed into a field is a parameter (`{ "$param": "email" }`). A non-sensitive one keeps
14
+ * what was typed as its default; a sensitive one (a password field, a one-time code, a card
15
+ * number, a value the agent marked) keeps no value at all, so replay needs it again.
16
+ * - A vault sign-in is a `browser_login` step with the site's name only: the values stay in
17
+ * the secret store and are read again at replay.
18
+ */
19
+ /** The flow file format this package writes and reads. */
20
+ export declare const FLOW_FORMAT_VERSION = 1;
21
+ /** Most steps one flow holds. */
22
+ export declare const MAX_FLOW_STEPS = 200;
23
+ /** The prefix of the flows an identity records by itself (`record.flows`). */
24
+ export declare const AUTO_PREFIX = "auto-";
25
+ export declare class FlowError extends Error {
26
+ constructor(message: string);
27
+ }
28
+ /** One way to find an element again, as a Playwright selector. */
29
+ export interface FlowLocator {
30
+ /** `generated` (Playwright's own), `role` (role and accessible name), `text`, `css`. */
31
+ kind: "generated" | "role" | "text" | "css";
32
+ selector: string;
33
+ }
34
+ /** An element a step acts on. */
35
+ export interface FlowTarget {
36
+ /** What the element is, for people and for the failure report ("Sign in button"). */
37
+ description?: string;
38
+ /** Tried in order on replay; the first that matches exactly one visible element wins. */
39
+ locators: FlowLocator[];
40
+ /** The snapshot ref the element had when it was recorded; never used to replay. */
41
+ ref?: string;
42
+ }
43
+ /** A parameter slot inside a step's arguments. */
44
+ export interface ParamRef {
45
+ $param: string;
46
+ }
47
+ export interface FlowParam {
48
+ name: string;
49
+ /** True: the value is never stored, and replay needs it (`keychain:<item>` keeps it from the model). */
50
+ sensitive: boolean;
51
+ /** What was typed when it was recorded; never present for a sensitive parameter. */
52
+ default?: string;
53
+ /** The field it was typed into. */
54
+ description?: string;
55
+ }
56
+ export interface FlowStep {
57
+ tool: string;
58
+ /** The tool's arguments without its element targets; parameter slots are `ParamRef`s. */
59
+ args: Record<string, unknown>;
60
+ /** The element of each target argument, by its path in `args` (`target`, `fields.0.target`). */
61
+ targets?: Record<string, FlowTarget>;
62
+ /** The URL of the page when the step ran (no query or fragment). */
63
+ url?: string;
64
+ }
65
+ export interface Flow {
66
+ version: number;
67
+ name: string;
68
+ description?: string;
69
+ identity: string;
70
+ created: string;
71
+ updated: string;
72
+ params: FlowParam[];
73
+ steps: FlowStep[];
74
+ }
75
+ export interface FlowSummary {
76
+ name: string;
77
+ description?: string;
78
+ steps: number;
79
+ params: {
80
+ name: string;
81
+ sensitive: boolean;
82
+ hasDefault: boolean;
83
+ }[];
84
+ /** First page the flow visits, when it navigates. */
85
+ start?: string;
86
+ auto: boolean;
87
+ updated: string;
88
+ file: string;
89
+ }
90
+ export declare function assertFlowName(name: string): void;
91
+ /** Where an identity's flows live: `<data>/browser/flows/<id>`. */
92
+ export declare function flowsDir(id: string, env?: NodeJS.ProcessEnv): string;
93
+ export declare function flowPath(id: string, name: string, env?: NodeJS.ProcessEnv): string;
94
+ /** Everything wrong with a parsed flow file; empty when it is valid. */
95
+ export declare function flowProblems(raw: unknown): string[];
96
+ /** The parameter names a value uses, at any depth. */
97
+ export declare function paramRefs(value: unknown): string[];
98
+ /** A copy of `value` with every parameter slot replaced by its value. */
99
+ export declare function fillParams(value: unknown, values: Record<string, string>): unknown;
100
+ /** Reads `a.b.0.c` of an object. */
101
+ export declare function getPath(obj: unknown, path: string): unknown;
102
+ /** Sets `a.b.0.c` of an object that already has every level but the last. */
103
+ export declare function setPath(obj: Record<string, unknown>, path: string, value: unknown): void;
104
+ /**
105
+ * The parameter values a replay runs with: the given ones, then the defaults. `missing` lists
106
+ * the parameters with neither (every sensitive one not given), `unknown` the given names the
107
+ * flow does not have.
108
+ */
109
+ export declare function resolveParams(flow: Pick<Flow, "params">, given?: Record<string, string>): {
110
+ values: Record<string, string>;
111
+ missing: FlowParam[];
112
+ unknown: string[];
113
+ };
114
+ /** A step in a few words: `browser_click "Sign in" button`, `browser_navigate https://...`. */
115
+ export declare function describeStep(step: FlowStep): string;
116
+ /** Writes a flow (mode 600, through a rename). Validates first. */
117
+ export declare function writeFlow(id: string, flow: Flow, env?: NodeJS.ProcessEnv): string;
118
+ /** A saved flow; throws a FlowError when there is none or it cannot be used. */
119
+ export declare function readFlow(id: string, name: string, env?: NodeJS.ProcessEnv): Flow;
120
+ /** The identity's saved flows, newest first. Files that cannot be read are left out. */
121
+ export declare function listFlows(id: string, env?: NodeJS.ProcessEnv): FlowSummary[];
122
+ /** Deletes a flow; false when there was none. */
123
+ export declare function removeFlow(id: string, name: string, env?: NodeJS.ProcessEnv): boolean;
124
+ /** Keeps the newest `keep` flows the identity recorded by itself; returns how many went. */
125
+ export declare function rotateAutoFlows(id: string, keep: number, env?: NodeJS.ProcessEnv): number;
126
+ /** Removes every flow of an identity (when the identity goes). */
127
+ export declare function removeFlows(id: string, env?: NodeJS.ProcessEnv): void;