turno-browser 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +95 -123
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +117 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +600 -0
  7. package/dist/api.d.ts +90 -2
  8. package/dist/api.js +41 -4
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/background-state.d.ts +54 -0
  12. package/dist/background-state.js +97 -0
  13. package/dist/background.d.ts +69 -0
  14. package/dist/background.js +458 -0
  15. package/dist/batch.d.ts +5 -0
  16. package/dist/batch.js +3 -3
  17. package/dist/bin/mcp.js +103 -6
  18. package/dist/captcha.d.ts +77 -0
  19. package/dist/captcha.js +334 -0
  20. package/dist/cdp-relay.d.ts +20 -0
  21. package/dist/cdp-relay.js +101 -0
  22. package/dist/chrome-features.d.ts +23 -0
  23. package/dist/chrome-features.js +44 -0
  24. package/dist/cli/background.d.ts +11 -0
  25. package/dist/cli/background.js +132 -0
  26. package/dist/cli/commands.d.ts +16 -0
  27. package/dist/cli/commands.js +515 -0
  28. package/dist/cli/context.d.ts +75 -0
  29. package/dist/cli/context.js +44 -0
  30. package/dist/cli/do-background.d.ts +27 -0
  31. package/dist/cli/do-background.js +212 -0
  32. package/dist/cli/do.d.ts +85 -0
  33. package/dist/cli/do.js +558 -0
  34. package/dist/cli/flows.d.ts +28 -0
  35. package/dist/cli/flows.js +303 -0
  36. package/dist/cli/identity.d.ts +37 -0
  37. package/dist/cli/identity.js +906 -0
  38. package/dist/cli/live.d.ts +7 -0
  39. package/dist/cli/live.js +99 -0
  40. package/dist/cli/main.d.ts +16 -0
  41. package/dist/cli/main.js +171 -0
  42. package/dist/cli/secret.d.ts +4 -0
  43. package/dist/cli/secret.js +151 -0
  44. package/dist/cli/session.d.ts +6 -0
  45. package/dist/cli/session.js +106 -0
  46. package/dist/cli/setup.d.ts +7 -0
  47. package/dist/cli/setup.js +180 -0
  48. package/dist/cli/vault.d.ts +5 -0
  49. package/dist/cli/vault.js +192 -0
  50. package/dist/client.d.ts +82 -0
  51. package/dist/client.js +303 -0
  52. package/dist/diagnose.d.ts +7 -0
  53. package/dist/diagnose.js +61 -6
  54. package/dist/doctor.d.ts +37 -3
  55. package/dist/doctor.js +264 -6
  56. package/dist/engine-attach.d.ts +27 -0
  57. package/dist/engine-attach.js +165 -0
  58. package/dist/engine-camoufox.d.ts +32 -0
  59. package/dist/engine-camoufox.js +271 -0
  60. package/dist/engine-lightpanda.d.ts +72 -0
  61. package/dist/engine-lightpanda.js +293 -0
  62. package/dist/engine.d.ts +63 -11
  63. package/dist/engine.js +106 -29
  64. package/dist/flows.d.ts +127 -0
  65. package/dist/flows.js +294 -0
  66. package/dist/governor.d.ts +42 -7
  67. package/dist/governor.js +82 -32
  68. package/dist/health.js +2 -1
  69. package/dist/host.d.ts +38 -2
  70. package/dist/host.js +689 -52
  71. package/dist/human-input.d.ts +84 -0
  72. package/dist/human-input.js +448 -0
  73. package/dist/humanize.d.ts +123 -0
  74. package/dist/humanize.js +241 -0
  75. package/dist/identities.js +4 -1
  76. package/dist/idle-timer.d.ts +12 -0
  77. package/dist/idle-timer.js +25 -0
  78. package/dist/index.d.ts +13 -4
  79. package/dist/index.js +7 -1
  80. package/dist/lifecycle.d.ts +11 -1
  81. package/dist/lifecycle.js +11 -2
  82. package/dist/live-client.d.ts +22 -0
  83. package/dist/live-client.js +95 -0
  84. package/dist/live-page.d.ts +4 -0
  85. package/dist/live-page.js +144 -0
  86. package/dist/live-server.d.ts +173 -0
  87. package/dist/live-server.js +643 -0
  88. package/dist/live.d.ts +120 -0
  89. package/dist/live.js +204 -0
  90. package/dist/login-tool.d.ts +13 -0
  91. package/dist/login-tool.js +8 -3
  92. package/dist/login.d.ts +4 -1
  93. package/dist/login.js +12 -2
  94. package/dist/names.d.ts +28 -0
  95. package/dist/names.js +25 -0
  96. package/dist/network-chrome.d.ts +74 -0
  97. package/dist/network-chrome.js +178 -0
  98. package/dist/network.d.ts +125 -0
  99. package/dist/network.js +264 -0
  100. package/dist/opt-in-settings.d.ts +69 -0
  101. package/dist/opt-in-settings.js +152 -0
  102. package/dist/recorder.d.ts +88 -0
  103. package/dist/recorder.js +538 -0
  104. package/dist/recordings.d.ts +116 -0
  105. package/dist/recordings.js +474 -0
  106. package/dist/redact.d.ts +7 -0
  107. package/dist/redact.js +18 -0
  108. package/dist/replay.d.ts +20 -0
  109. package/dist/replay.js +383 -0
  110. package/dist/reputation.d.ts +24 -2
  111. package/dist/reputation.js +63 -17
  112. package/dist/runtime-lock.js +3 -2
  113. package/dist/session-export.js +1 -1
  114. package/dist/session.d.ts +10 -2
  115. package/dist/session.js +10 -2
  116. package/dist/settings.d.ts +104 -2
  117. package/dist/settings.js +204 -6
  118. package/dist/sharing.d.ts +96 -0
  119. package/dist/sharing.js +269 -0
  120. package/dist/snippet.d.ts +8 -2
  121. package/dist/snippet.js +10 -4
  122. package/dist/tab-locks.d.ts +63 -0
  123. package/dist/tab-locks.js +179 -0
  124. package/dist/tools.d.ts +38 -0
  125. package/dist/tools.js +20 -1
  126. package/dist/tuning.d.ts +14 -0
  127. package/dist/tuning.js +9 -0
  128. package/dist/upstream.d.ts +11 -0
  129. package/dist/vault.js +5 -4
  130. package/npm-shrinkwrap.json +6 -5
  131. package/package.json +13 -7
@@ -0,0 +1,538 @@
1
+ import { AUTO_PREFIX, FlowError, FLOW_FORMAT_VERSION, MAX_FLOW_STEPS, assertFlowName, describeStep, flowPath, getPath, rotateAutoFlows, setPath, writeFlow, } from "./flows.js";
2
+ import { existsSync } from "node:fs";
3
+ import { upstream } from "./upstream.js";
4
+ /**
5
+ * Flow recording. While a session records (the agent called `browser_record`, or the
6
+ * identity has `record.flows`), every successful browser action is kept as a flow step, with
7
+ * the element it acted on found again in several ways. The host calls `capture` before a stock
8
+ * tool runs (the snapshot ref still points at the element then) and `commit` after it worked.
9
+ *
10
+ * Secrets never reach a flow file:
11
+ *
12
+ * - Typed text is always a parameter. It keeps what was typed as its default only when the
13
+ * field is not sensitive: a password field, an `autocomplete` of a password, a one-time code
14
+ * or a card, a field named like one (`password`, `otp`, `pin`, `cvv`, `token`...), or a value
15
+ * that is one of this server's vault values. The agent can mark more parameters sensitive
16
+ * when it stops a named recording, which is held in memory until then.
17
+ * - `browser_login` is recorded as its site name; the values are read from the vault again
18
+ * at replay.
19
+ * - Nothing else of a page (snapshots, results, values of other fields) is stored.
20
+ */
21
+ /** How many flows an identity keeps that it recorded by itself. */
22
+ const KEEP_AUTO_FLOWS = 20;
23
+ /** The element arguments of each tool a flow records; `browser_fill_form` has one per field. */
24
+ const TARGETS = {
25
+ browser_navigate: [],
26
+ browser_navigate_back: [],
27
+ browser_navigate_forward: [],
28
+ browser_reload: [],
29
+ browser_click: ["target"],
30
+ browser_hover: ["target"],
31
+ browser_type: ["target"],
32
+ browser_select_option: ["target"],
33
+ browser_check: ["target"],
34
+ browser_uncheck: ["target"],
35
+ browser_drag: ["startTarget", "endTarget"],
36
+ browser_press_key: [],
37
+ browser_wait_for: [],
38
+ browser_handle_dialog: [],
39
+ browser_tabs: [],
40
+ browser_file_upload: [],
41
+ browser_fill_form: [],
42
+ };
43
+ /** True when a flow keeps calls of this tool. */
44
+ function recordsTool(name, args) {
45
+ if (!(name in TARGETS))
46
+ return false;
47
+ // Listing tabs changes nothing.
48
+ return !(name === "browser_tabs" && (args.action ?? "list") === "list");
49
+ }
50
+ export const SECRET_AUTOCOMPLETE = /(^|\s)(current-password|new-password|one-time-code|cc-number|cc-csc|cc-exp(-month|-year)?)(\s|$)/i;
51
+ export const SECRET_NAME = /pass(word|wd|code)?|pwd|otp|totp|2fa|mfa|(^|[^a-z])pin([^a-z]|$)|cvv|cvc|csc|secret|token|ssn/i;
52
+ /** A field whose typed value must never be stored. */
53
+ export function secretField(info) {
54
+ if (info.type === "password")
55
+ return true;
56
+ if (SECRET_AUTOCOMPLETE.test(info.autocomplete))
57
+ return true;
58
+ return SECRET_NAME.test(`${info.name} ${info.id}`);
59
+ }
60
+ /**
61
+ * The values a `browser_type` or `browser_fill_form` call is about to put into secret fields
62
+ * (`secretField`), so a recording can stop its trace first. A target the page cannot resolve
63
+ * counts as not secret: the call then fails the same way.
64
+ */
65
+ export async function secretValues(page, tool, args) {
66
+ const pairs = tool === "browser_type"
67
+ ? [[args.target, args.text]]
68
+ : tool === "browser_fill_form" && Array.isArray(args.fields)
69
+ ? args.fields
70
+ .filter((f) => f.type === "textbox")
71
+ .map((f) => [f.target, f.value])
72
+ : [];
73
+ const out = [];
74
+ for (const [target, value] of pairs) {
75
+ if (typeof target !== "string" || typeof value !== "string" || !value)
76
+ continue;
77
+ const locator = page.locator(REF.test(target) ? `aria-ref=${target}` : target);
78
+ const info = await locator
79
+ .evaluate((el) => ({
80
+ type: (el.type || "").toLowerCase(),
81
+ autocomplete: el.getAttribute("autocomplete") ?? "",
82
+ name: el.getAttribute("name") ?? "",
83
+ id: el.id,
84
+ }), undefined, { timeout: 2_000 })
85
+ .catch(() => undefined);
86
+ if (info && secretField(info))
87
+ out.push(value);
88
+ }
89
+ return out;
90
+ }
91
+ /** Playwright's attribute value syntax: `"Sign in"s` (exact) for role and text selectors. */
92
+ function quoteExact(text) {
93
+ return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"s`;
94
+ }
95
+ /** A CSS string with its quotes escaped, for `:text-is()`. */
96
+ function quoteCss(text) {
97
+ return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
98
+ }
99
+ /**
100
+ * Role and accessible name from Playwright's generated locator when it is a role locator
101
+ * (`internal:role=button[name="Sign in"i]`). Asking the element for its aria snapshot instead
102
+ * would renumber the page's refs and break the call the agent is making.
103
+ */
104
+ export function roleFromSelector(selector) {
105
+ const m = /internal:role=([a-z]+)(?:\[name="((?:[^"\\]|\\.)*)"[is]?\])?$/.exec(selector);
106
+ if (!m)
107
+ return undefined;
108
+ return { role: m[1], ...(m[2] ? { name: JSON.parse(`"${m[2]}"`) } : {}) };
109
+ }
110
+ const ROLE_SKIP = new Set(["generic", "text", "none", "presentation", "paragraph"]);
111
+ const REF = /^(f\d+)?e\d+$/;
112
+ /**
113
+ * The element a target names, found again four ways: Playwright's own locator for it, its role
114
+ * and accessible name, its visible text and a CSS path. Elements in a frame keep the frame hop
115
+ * Playwright's locator starts with. Undefined when the element is not on the page.
116
+ */
117
+ async function captureTarget(page, target, element) {
118
+ const isRef = REF.test(target);
119
+ const description = element?.trim() || undefined;
120
+ const out = {
121
+ ...(description ? { description } : {}),
122
+ locators: [],
123
+ ...(isRef ? { ref: target } : {}),
124
+ };
125
+ let locator;
126
+ let generated;
127
+ if (isRef) {
128
+ locator = page.locator(`aria-ref=${target}`);
129
+ try {
130
+ generated = (await locator.normalize())._selector;
131
+ }
132
+ catch {
133
+ return undefined; // the ref is not in the current snapshot: upstream fails the call the same way
134
+ }
135
+ }
136
+ else {
137
+ // A selector or locator the agent wrote: upstream takes it again as is on replay.
138
+ generated = target;
139
+ try {
140
+ locator = page.locator(target);
141
+ }
142
+ catch {
143
+ return { target: { ...out, locators: [{ kind: "generated", selector: target }] } };
144
+ }
145
+ }
146
+ let frame = "";
147
+ if (generated) {
148
+ out.locators.push({ kind: "generated", selector: generated });
149
+ const hop = generated.lastIndexOf("internal:control=enter-frame >> ");
150
+ if (hop >= 0)
151
+ frame = generated.slice(0, hop + "internal:control=enter-frame >> ".length);
152
+ }
153
+ const aria = generated ? roleFromSelector(generated) : undefined;
154
+ if (aria?.name && !ROLE_SKIP.has(aria.role))
155
+ out.locators.push({ kind: "role", selector: `${frame}internal:role=${aria.role}[name=${quoteExact(aria.name)}]` });
156
+ const info = await locator
157
+ .evaluate((el) => {
158
+ const input = el;
159
+ const esc = (v) => CSS.escape(v);
160
+ const unique = (sel) => {
161
+ try {
162
+ return el.ownerDocument.querySelectorAll(sel).length === 1;
163
+ }
164
+ catch {
165
+ return false;
166
+ }
167
+ };
168
+ let css = "";
169
+ const name = el.getAttribute("name");
170
+ if (el.id && unique(`#${esc(el.id)}`))
171
+ css = `#${esc(el.id)}`;
172
+ else if (name && unique(`${el.localName}[name="${esc(name)}"]`))
173
+ css = `${el.localName}[name="${esc(name)}"]`;
174
+ else {
175
+ const parts = [];
176
+ let node = el;
177
+ while (node && node.localName !== "html") {
178
+ if (node.id && unique(`#${esc(node.id)}`)) {
179
+ parts.unshift(`#${esc(node.id)}`);
180
+ break;
181
+ }
182
+ const tag = node.localName;
183
+ const parent = node.parentElement;
184
+ const same = parent ? Array.from(parent.children).filter((c) => c.localName === tag) : [];
185
+ parts.unshift(same.length > 1 ? `${tag}:nth-of-type(${same.indexOf(node) + 1})` : tag);
186
+ node = parent;
187
+ }
188
+ css = parts.join(" > ");
189
+ }
190
+ const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
191
+ return {
192
+ tag: el.localName,
193
+ type: (input.type || "").toLowerCase(),
194
+ autocomplete: el.getAttribute("autocomplete") ?? "",
195
+ name: name ?? "",
196
+ id: el.id,
197
+ text: text.length <= 80 ? text : "",
198
+ css,
199
+ };
200
+ }, undefined, { timeout: 2_000 })
201
+ .catch(() => undefined);
202
+ if (info) {
203
+ const field = ["input", "textarea", "select"].includes(info.tag);
204
+ // The tag keeps the text from matching another element (a heading that reads like the button).
205
+ if (info.text && !field)
206
+ out.locators.push({ kind: "text", selector: `${frame}css=${info.tag}:text-is(${quoteCss(info.text)})` });
207
+ if (info.css)
208
+ out.locators.push({ kind: "css", selector: `${frame}css=${info.css}` });
209
+ }
210
+ out.locators = out.locators.filter((l, i) => out.locators.findIndex((m) => m.selector === l.selector) === i);
211
+ const label = aria?.name ?? info?.name ?? description;
212
+ return { target: out, ...(info ? { info } : {}), ...(label ? { label } : {}) };
213
+ }
214
+ /** A parameter name from a field's label: "E-mail address" is `e_mail_address`. */
215
+ function paramBase(label) {
216
+ const slug = (label ?? "")
217
+ .toLowerCase()
218
+ .normalize("NFKD")
219
+ .replace(/[̀-ͯ]/g, "")
220
+ .replace(/[^a-z0-9]+/g, "_")
221
+ .replace(/^_+|_+$/g, "")
222
+ .slice(0, 40);
223
+ return slug || "text";
224
+ }
225
+ /** One flow being recorded. */
226
+ class Draft {
227
+ name;
228
+ description;
229
+ params = [];
230
+ steps = [];
231
+ created = new Date().toISOString();
232
+ full = false;
233
+ constructor(name, description) {
234
+ this.name = name;
235
+ this.description = description;
236
+ }
237
+ param(slot) {
238
+ const base = paramBase(slot.label);
239
+ let name = base;
240
+ for (let n = 2; this.params.some((p) => p.name === name); n++)
241
+ name = `${base}_${n}`;
242
+ this.params.push({
243
+ name,
244
+ sensitive: slot.sensitive,
245
+ ...(slot.sensitive ? {} : { default: slot.value }),
246
+ ...(slot.description ? { description: slot.description } : {}),
247
+ });
248
+ return name;
249
+ }
250
+ /** Adds a step; false once the flow is full. */
251
+ add(pending) {
252
+ if (this.steps.length >= MAX_FLOW_STEPS) {
253
+ this.full = true;
254
+ return false;
255
+ }
256
+ const step = structuredClone(pending.step);
257
+ for (const slot of pending.slots)
258
+ setPath(step.args, slot.path, { $param: this.param(slot) });
259
+ this.steps.push(step);
260
+ return true;
261
+ }
262
+ flow(identity) {
263
+ return {
264
+ version: FLOW_FORMAT_VERSION,
265
+ name: this.name,
266
+ ...(this.description ? { description: this.description } : {}),
267
+ identity,
268
+ created: this.created,
269
+ updated: new Date().toISOString(),
270
+ params: this.params.map((p) => ({ ...p })),
271
+ steps: this.steps.map((s) => structuredClone(s)),
272
+ };
273
+ }
274
+ }
275
+ /** The URL of a page without its query and fragment (they can carry tokens). */
276
+ function plainUrl(url) {
277
+ try {
278
+ const u = new URL(url);
279
+ if (u.protocol === "about:")
280
+ return undefined;
281
+ return `${u.origin}${u.pathname}`;
282
+ }
283
+ catch {
284
+ return undefined;
285
+ }
286
+ }
287
+ /** The recorder of one MCP session. */
288
+ export class FlowRecorder {
289
+ identity;
290
+ redactor;
291
+ autoFlows;
292
+ named;
293
+ overwrite = false;
294
+ auto;
295
+ suspended = 0;
296
+ constructor(identity, redactor,
297
+ /** identity.json `record.flows`: record every session as `auto-<time>`. */
298
+ autoFlows) {
299
+ this.identity = identity;
300
+ this.redactor = redactor;
301
+ this.autoFlows = autoFlows;
302
+ }
303
+ /** True when a step would be kept now. */
304
+ get active() {
305
+ return this.suspended === 0 && (this.named !== undefined || this.autoFlows());
306
+ }
307
+ get recording() {
308
+ const d = this.named;
309
+ return d && { name: d.name, steps: d.steps.length, params: d.params.length, full: d.full };
310
+ }
311
+ start(name, description, overwrite) {
312
+ assertFlowName(name);
313
+ if (name.startsWith(AUTO_PREFIX))
314
+ throw new FlowError(`flow names starting with "${AUTO_PREFIX}" are kept for the identity's own recordings`);
315
+ if (this.named)
316
+ throw new FlowError(`already recording flow "${this.named.name}"; stop or cancel it first`);
317
+ if (!overwrite && existsSync(flowPath(this.identity.id, name, this.identity.env)))
318
+ throw new FlowError(`flow "${name}" exists; pass overwrite: true to replace it, or pick another name`);
319
+ this.named = new Draft(name, description);
320
+ this.overwrite = overwrite;
321
+ }
322
+ /** Saves the named flow, with `sensitive` parameters' values dropped. */
323
+ stop(sensitive = [], description) {
324
+ const draft = this.named;
325
+ if (!draft)
326
+ throw new FlowError("no flow is being recorded; start one with action start");
327
+ const unknown = sensitive.filter((s) => !draft.params.some((p) => p.name === s));
328
+ if (unknown.length)
329
+ throw new FlowError(`no parameter ${unknown.map((u) => `"${u}"`).join(", ")} in this flow (its parameters: ${draft.params.map((p) => p.name).join(", ") || "none"})`);
330
+ if (!draft.steps.length)
331
+ throw new FlowError("the flow has no steps yet; nothing was saved (cancel it, or act first)");
332
+ const flow = draft.flow(this.identity.id);
333
+ if (description)
334
+ flow.description = description;
335
+ for (const p of flow.params)
336
+ if (sensitive.includes(p.name)) {
337
+ p.sensitive = true;
338
+ delete p.default;
339
+ }
340
+ if (!this.overwrite && existsSync(flowPath(this.identity.id, flow.name, this.identity.env)))
341
+ throw new FlowError(`flow "${flow.name}" was saved by someone else meanwhile; stop with another name`);
342
+ const file = writeFlow(this.identity.id, flow, this.identity.env);
343
+ this.named = undefined;
344
+ return { flow, file };
345
+ }
346
+ cancel() {
347
+ const had = this.named !== undefined;
348
+ this.named = undefined;
349
+ return had;
350
+ }
351
+ /** Runs `fn` without recording its steps (a replay is recorded as one step). */
352
+ async suspend(fn) {
353
+ this.suspended++;
354
+ try {
355
+ return await fn();
356
+ }
357
+ finally {
358
+ this.suspended--;
359
+ }
360
+ }
361
+ /** A stock tool call about to run, as a step; undefined when it is not one a flow keeps. */
362
+ async capture(tool, args, page) {
363
+ if (!this.active || !recordsTool(tool, args))
364
+ return undefined;
365
+ const { element: _element, startElement: _start, endElement: _end, ...rest } = args;
366
+ const step = { tool, args: structuredClone(rest) };
367
+ const slots = [];
368
+ const paths = tool === "browser_fill_form" && Array.isArray(args.fields)
369
+ ? args.fields.map((_, i) => `fields.${i}.target`)
370
+ : (TARGETS[tool] ?? []);
371
+ const describedBy = {
372
+ target: args.element,
373
+ startTarget: args.startElement,
374
+ endTarget: args.endElement,
375
+ };
376
+ const infos = {};
377
+ for (const path of paths) {
378
+ const value = getPath(args, path);
379
+ if (typeof value !== "string" || !page)
380
+ return undefined;
381
+ const fieldName = path.startsWith("fields.")
382
+ ? getPath(args, path.replace(/target$/, "name"))
383
+ : undefined;
384
+ const captured = await captureTarget(page, value, describedBy[path] ?? fieldName);
385
+ if (!captured)
386
+ return undefined;
387
+ step.targets ??= {};
388
+ step.targets[path] = captured.target;
389
+ infos[path] = { ...(captured.info ? { info: captured.info } : {}), label: fieldName ?? captured.label };
390
+ }
391
+ // Drop the emptied target keys so the step's args are only what replay passes again.
392
+ for (const path of paths) {
393
+ const keys = path.split(".");
394
+ const holder = keys.length > 1 ? getPath(step.args, keys.slice(0, -1).join(".")) : step.args;
395
+ if (holder && typeof holder === "object")
396
+ delete holder[keys[keys.length - 1]];
397
+ }
398
+ const typed = (path, value, at) => {
399
+ if (typeof value !== "string")
400
+ return;
401
+ const meta = infos[at];
402
+ const sensitive = (meta?.info ? secretField(meta.info) : false) || this.redactor.covers(value);
403
+ slots.push({
404
+ path,
405
+ value,
406
+ sensitive,
407
+ ...(meta?.label ? { label: meta.label } : {}),
408
+ ...(step.targets?.[at]?.description ? { description: step.targets[at].description } : {}),
409
+ });
410
+ };
411
+ if (tool === "browser_type")
412
+ typed("text", args.text, "target");
413
+ if (tool === "browser_handle_dialog" && typeof args.promptText === "string") {
414
+ slots.push({
415
+ path: "promptText",
416
+ value: args.promptText,
417
+ sensitive: this.redactor.covers(args.promptText),
418
+ label: "prompt",
419
+ });
420
+ }
421
+ if (tool === "browser_fill_form" && Array.isArray(args.fields)) {
422
+ args.fields.forEach((f, i) => {
423
+ // A checkbox or radio value is "true" or "false": part of the flow, not a parameter.
424
+ if (f.type === "checkbox" || f.type === "radio")
425
+ return;
426
+ typed(`fields.${i}.value`, f.value, `fields.${i}.target`);
427
+ });
428
+ }
429
+ const url = page ? plainUrl(page.url()) : undefined;
430
+ if (url)
431
+ step.url = url;
432
+ return { step, slots };
433
+ }
434
+ /** Keeps a captured step after its tool worked. */
435
+ commit(pending) {
436
+ if (!this.active)
437
+ return;
438
+ this.named?.add(pending);
439
+ if (this.autoFlows())
440
+ this.commitAuto(pending);
441
+ }
442
+ /** A turno tool as a step: `browser_login` (site only) or `browser_replay` (its flow and parameters). */
443
+ record(tool, args, slots = []) {
444
+ this.commit({ step: { tool, args: structuredClone(args) }, slots });
445
+ }
446
+ commitAuto(pending) {
447
+ if (!this.auto) {
448
+ const stamp = new Date().toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
449
+ this.auto = new Draft(`${AUTO_PREFIX}${stamp}`, "recorded by the identity (record.flows)");
450
+ }
451
+ if (!this.auto.add(pending))
452
+ return;
453
+ try {
454
+ writeFlow(this.identity.id, this.auto.flow(this.identity.id), this.identity.env);
455
+ if (this.auto.steps.length === 1)
456
+ rotateAutoFlows(this.identity.id, KEEP_AUTO_FLOWS, this.identity.env);
457
+ }
458
+ catch {
459
+ /* best effort: a full disk must not break a tool call */
460
+ }
461
+ }
462
+ }
463
+ function recordSchema() {
464
+ const z = upstream().utils.z;
465
+ return {
466
+ name: "browser_record",
467
+ title: "Record browser actions as a flow",
468
+ description: [
469
+ "Record the browser actions of this session as a named flow that browser_replay can run again later without working the page out.",
470
+ "action start begins recording (name required); every browser action that works from then on is kept: navigate, click, type, fill_form, select_option, press_key, hover, drag, tabs, wait_for, browser_login (the site only) and browser_replay.",
471
+ "action stop saves the flow; list in sensitive the parameters whose values must not be kept (password fields, one-time codes and vault sign-ins are never kept anyway). action cancel drops it; action status says what is recording.",
472
+ "Typed text becomes a parameter of the flow, with what you typed as its default unless it is sensitive.",
473
+ ].join(" "),
474
+ inputSchema: z.object({
475
+ action: z.string().describe('"start", "stop", "cancel" or "status"'),
476
+ name: z
477
+ .string()
478
+ .optional()
479
+ .describe("The flow name for start: lowercase letters, digits, - and _ (for example submit-timesheet)"),
480
+ description: z.string().optional().describe("What the flow does, for start or stop"),
481
+ sensitive: z.array(z.string()).optional().describe("For stop: parameter names whose values must not be saved"),
482
+ overwrite: z.boolean().optional().describe("For start: replace a saved flow of the same name"),
483
+ }),
484
+ type: "action",
485
+ };
486
+ }
487
+ /** `browser_record`. */
488
+ export function recordTool() {
489
+ let built;
490
+ return {
491
+ get schema() {
492
+ built ??= recordSchema();
493
+ return built;
494
+ },
495
+ browser: false,
496
+ async handle(ctx, params) {
497
+ const recorder = ctx.recorder;
498
+ if (!recorder)
499
+ throw new FlowError("browser_record needs a browser identity: this server runs without --identity");
500
+ const action = String(params.action);
501
+ const text = (lines) => ({
502
+ content: [{ type: "text", text: ["### Result", ...lines].join("\n") }],
503
+ });
504
+ if (action === "start") {
505
+ if (typeof params.name !== "string")
506
+ throw new FlowError('action start needs a name, for example "submit-timesheet"');
507
+ recorder.start(params.name, params.description, params.overwrite === true);
508
+ return text([
509
+ `Recording flow "${params.name}". Browser actions that work are kept from now on; call browser_record with action "stop" to save it.`,
510
+ ]);
511
+ }
512
+ if (action === "stop") {
513
+ const { flow, file } = recorder.stop(params.sensitive ?? [], params.description);
514
+ const params_ = flow.params.map((p) => `- ${p.name}${p.sensitive ? " (sensitive: not saved, give it at replay)" : ` (default kept)`}`);
515
+ return text([
516
+ `Saved flow "${flow.name}" with ${flow.steps.length} step${flow.steps.length === 1 ? "" : "s"} to ${file}.`,
517
+ ...flow.steps.map((s, i) => `${i + 1}. ${describeStep(s)}`),
518
+ ...(params_.length ? ["Parameters:", ...params_] : []),
519
+ `Run it again with browser_replay {"flow": "${flow.name}"}.`,
520
+ ]);
521
+ }
522
+ if (action === "cancel")
523
+ return text([
524
+ recorder.cancel() ? "Dropped the flow being recorded; nothing was saved." : "No flow was being recorded.",
525
+ ]);
526
+ if (action === "status") {
527
+ const r = recorder.recording;
528
+ return text([
529
+ r
530
+ ? `Recording flow "${r.name}": ${r.steps} step${r.steps === 1 ? "" : "s"}, ${r.params} parameter${r.params === 1 ? "" : "s"}${r.full ? " (full: later steps are not kept)" : ""}.`
531
+ : "No named flow is being recorded.",
532
+ ]);
533
+ }
534
+ throw new FlowError(`unknown action "${action}": use start, stop, cancel or status`);
535
+ },
536
+ };
537
+ }
538
+ //# sourceMappingURL=recorder.js.map
@@ -0,0 +1,116 @@
1
+ import type { BrowserContext, Page } from "patchright-core";
2
+ import type { IdentityRef } from "./engine.js";
3
+ import type { Redactor, VaultGuard } from "./redact.js";
4
+ import type { RecordSettings } from "./settings.js";
5
+ export declare function recordingsDir(id: string, env?: NodeJS.ProcessEnv): string;
6
+ /** Where Playwright writes a trace's raw files while it records (the launch's `tracesDir`). */
7
+ export declare function tracesTmpDir(id: string, env?: NodeJS.ProcessEnv): string;
8
+ export interface RecordingSummary {
9
+ name: string;
10
+ dir: string;
11
+ title: string;
12
+ started: string;
13
+ ended?: string;
14
+ steps: number;
15
+ screenshots: number;
16
+ traces: {
17
+ file: string;
18
+ from: number;
19
+ to: number;
20
+ bytes: number;
21
+ }[];
22
+ discarded: number;
23
+ bytes: number;
24
+ notes: string[];
25
+ }
26
+ /** An identity's recordings, newest first. */
27
+ export declare function listRecordings(id: string, env?: NodeJS.ProcessEnv): RecordingSummary[];
28
+ /**
29
+ * The command that opens a trace in the trace viewer patchright-core ships (its own
30
+ * `show-trace`, served on 127.0.0.1 and opened in the default browser). Never `npx`, which
31
+ * would download whatever package has that name.
32
+ */
33
+ export declare function traceViewerCommand(file: string): {
34
+ command: string;
35
+ args: string[];
36
+ };
37
+ /** Runs the trace viewer until the person stops it; resolves with its exit code. */
38
+ export declare function openTraceViewer(file: string, env?: NodeJS.ProcessEnv): Promise<number>;
39
+ /**
40
+ * The text of every entry of a zip, images left out. Handles stored and deflated entries (what
41
+ * Playwright writes); throws on anything else, so a caller can treat the file as unreadable.
42
+ */
43
+ export declare function zipTexts(buf: Buffer): {
44
+ name: string;
45
+ text: string;
46
+ }[];
47
+ /** The secret labels a trace file holds; `["unreadable"]` when it cannot be searched. */
48
+ export declare function traceLeaks(file: string, redactor: Redactor): string[];
49
+ export interface RecordingOptions {
50
+ identity: IdentityRef;
51
+ settings: RecordSettings;
52
+ context: BrowserContext;
53
+ redactor: Redactor;
54
+ guard: VaultGuard;
55
+ /** The session title (the client's name), shown by `turno browser traces`. */
56
+ title: string;
57
+ /** The browser's idle limit: the trace is saved shortly before it, while Chrome still runs. */
58
+ idleMs?: number;
59
+ /** Why traces cannot be recorded in this session (another trace owner); screenshots still are. */
60
+ noTraces?: string;
61
+ now?: () => Date;
62
+ }
63
+ /** The recording of one browser session (one launch). */
64
+ export declare class Recording {
65
+ private readonly o;
66
+ readonly dir: string;
67
+ private readonly index;
68
+ private trace;
69
+ private segment;
70
+ private segmentFrom;
71
+ private flushing;
72
+ private timer;
73
+ private readonly cap;
74
+ private bytes;
75
+ private capNoted;
76
+ private closed;
77
+ private constructor();
78
+ /** Starts a recording for a launched browser; undefined when identity.json asks for none. */
79
+ static open(o: RecordingOptions): Promise<Recording | undefined>;
80
+ private get others();
81
+ /** Deletes the oldest other recordings until they take at most `limit` bytes. */
82
+ private rotate;
83
+ /** Room for `size` more bytes, deleting older recordings first; false when the cap is reached. */
84
+ private room;
85
+ private write;
86
+ private startTrace;
87
+ /** Stops the trace and keeps the file, unless it holds a secret or passes the cap. */
88
+ private stopTrace;
89
+ /** Before a tool call: waits for a save in progress and starts the trace again when it may. */
90
+ beforeCall(): Promise<void>;
91
+ /** After a tool call: saves the trace shortly before the idle limit would close Chrome. */
92
+ callEnded(): void;
93
+ /**
94
+ * Before a secret goes into `page` (a vault fill, a password typed, a sensitive parameter):
95
+ * saves the trace and holds `page` in the vault guard, so neither the trace nor a
96
+ * screenshot starts again until it navigates.
97
+ */
98
+ pauseForSecret(page: Page | undefined): Promise<void>;
99
+ /**
100
+ * The user takes over the browser (the live view's pause): the trace is saved, so what the
101
+ * user does is not in it, and starts again at the agent's next call.
102
+ */
103
+ pauseForUser(): Promise<void>;
104
+ /** After an action: one line in the index and, when asked, a screenshot. */
105
+ afterStep(step: {
106
+ tool: string;
107
+ element?: unknown;
108
+ ok: boolean;
109
+ page?: Page;
110
+ screenshot: boolean;
111
+ }): Promise<void>;
112
+ /** Before turno closes the browser: saves the trace. */
113
+ close(): Promise<void>;
114
+ /** The browser went away on its own (a crash, a kill): the trace in progress is lost. */
115
+ abandon(): void;
116
+ }