turno-browser 0.6.0 → 0.8.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 (76) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +13 -5
  3. package/dist/act.js +4 -29
  4. package/dist/agent-cursor-overlay.d.ts +95 -0
  5. package/dist/agent-cursor-overlay.js +358 -0
  6. package/dist/agent-cursor.d.ts +191 -0
  7. package/dist/agent-cursor.js +494 -0
  8. package/dist/api.d.ts +8 -3
  9. package/dist/api.js +6 -3
  10. package/dist/argv.d.ts +2 -1
  11. package/dist/argv.js +7 -1
  12. package/dist/bin/mcp.js +5 -0
  13. package/dist/cli/commands.js +12 -3
  14. package/dist/cli/completion.js +3 -0
  15. package/dist/cli/context.d.ts +2 -0
  16. package/dist/cli/context.js +8 -4
  17. package/dist/cli/do-background.d.ts +2 -0
  18. package/dist/cli/do-background.js +15 -0
  19. package/dist/cli/do.d.ts +4 -0
  20. package/dist/cli/do.js +17 -1
  21. package/dist/cli/flows.js +3 -0
  22. package/dist/cli/identity.d.ts +2 -0
  23. package/dist/cli/identity.js +67 -11
  24. package/dist/cli/init.d.ts +12 -0
  25. package/dist/cli/init.js +219 -0
  26. package/dist/cli/login-summary.d.ts +6 -0
  27. package/dist/cli/login-summary.js +11 -0
  28. package/dist/cli/main.js +3 -0
  29. package/dist/cli/setup.d.ts +32 -0
  30. package/dist/cli/setup.js +32 -23
  31. package/dist/doctor.js +18 -2
  32. package/dist/engine-camoufox.js +1 -0
  33. package/dist/engine-lightpanda.js +1 -0
  34. package/dist/host.d.ts +7 -0
  35. package/dist/host.js +330 -68
  36. package/dist/human-input.d.ts +5 -0
  37. package/dist/human-input.js +1 -1
  38. package/dist/human-step-overlay.d.ts +73 -0
  39. package/dist/human-step-overlay.js +285 -0
  40. package/dist/human-step.d.ts +128 -0
  41. package/dist/human-step.js +521 -0
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +2 -2
  44. package/dist/live-server.d.ts +7 -3
  45. package/dist/live-server.js +13 -15
  46. package/dist/live.d.ts +20 -1
  47. package/dist/live.js +52 -10
  48. package/dist/login.d.ts +22 -2
  49. package/dist/login.js +95 -7
  50. package/dist/network-redact.d.ts +28 -0
  51. package/dist/network-redact.js +202 -0
  52. package/dist/recorder.d.ts +0 -21
  53. package/dist/recorder.js +1 -41
  54. package/dist/recordings.d.ts +5 -0
  55. package/dist/recordings.js +4 -2
  56. package/dist/redact.d.ts +7 -0
  57. package/dist/redact.js +32 -1
  58. package/dist/replay.d.ts +2 -0
  59. package/dist/replay.js +33 -14
  60. package/dist/reputation.d.ts +5 -0
  61. package/dist/reputation.js +12 -7
  62. package/dist/sensitive.d.ts +79 -0
  63. package/dist/sensitive.js +275 -0
  64. package/dist/session.d.ts +12 -0
  65. package/dist/session.js +24 -0
  66. package/dist/settings.d.ts +12 -2
  67. package/dist/settings.js +14 -2
  68. package/dist/tools.d.ts +5 -0
  69. package/dist/tools.js +9 -1
  70. package/dist/tuning.d.ts +4 -1
  71. package/dist/tuning.js +1 -0
  72. package/dist/upstream.d.ts +5 -0
  73. package/dist/watch.d.ts +60 -0
  74. package/dist/watch.js +114 -0
  75. package/npm-shrinkwrap.json +2 -2
  76. package/package.json +1 -1
@@ -0,0 +1,275 @@
1
+ /** What a masked value reads in a snapshot. */
2
+ export const SENSITIVE_MARK = "[sensitive field]";
3
+ const PASSWORD_AUTOCOMPLETE = /(^|\s)(current-password|new-password)(\s|$)/i;
4
+ const CODE_AUTOCOMPLETE = /(^|\s)one-time-code(\s|$)/i;
5
+ const CARD_AUTOCOMPLETE = /(^|\s)(cc-number|cc-csc|cc-exp(-month|-year)?)(\s|$)/i;
6
+ /** Broad on purpose: a flow never keeps what was typed into a field named like this. */
7
+ const SECRET_NAME = /pass(word|wd|code)?|pwd|otp|totp|2fa|mfa|(^|[^a-z])pin([^a-z]|$)|cvv|cvc|csc|secret|token|ssn/i;
8
+ const PASSWORD_WORD = /^(pass|pwd|passwd|passcode|passphrase)$|password/;
9
+ const CODE_WORDS = new Set(["otp", "totp", "hotp", "2fa", "mfa", "tfa", "onetime"]);
10
+ /** The words of a name: `newPassword`, `new-password` and `new_password` are `new password`. */
11
+ export function wordsOf(name) {
12
+ return name
13
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
14
+ .toLowerCase()
15
+ .split(/[^a-z0-9]+/)
16
+ .filter(Boolean);
17
+ }
18
+ function nameKind(name) {
19
+ const words = wordsOf(name);
20
+ if (words.some((w) => PASSWORD_WORD.test(w)))
21
+ return "password";
22
+ if (words.some((w) => CODE_WORDS.has(w)))
23
+ return "one-time code";
24
+ for (let i = 0; i + 1 < words.length; i++)
25
+ if (words[i] === "one" && words[i + 1] === "time")
26
+ return "one-time code";
27
+ return undefined;
28
+ }
29
+ /** The kind of a field, or undefined when its value is nobody's secret. */
30
+ export function fieldKind(info) {
31
+ if (info.type.toLowerCase() === "password")
32
+ return "password";
33
+ if (PASSWORD_AUTOCOMPLETE.test(info.autocomplete))
34
+ return "password";
35
+ if (CODE_AUTOCOMPLETE.test(info.autocomplete))
36
+ return "one-time code";
37
+ if (CARD_AUTOCOMPLETE.test(info.autocomplete))
38
+ return "card";
39
+ const named = nameKind(info.name) ?? nameKind(info.id);
40
+ if (named)
41
+ return named;
42
+ return SECRET_NAME.test(`${info.name} ${info.id}`) ? "secret" : undefined;
43
+ }
44
+ /** A field whose typed value must never be stored (a flow, a natural language prompt). */
45
+ export function secretField(info) {
46
+ return fieldKind(info) !== undefined;
47
+ }
48
+ /** A field only the person or the vault fills, whose value no result shows. */
49
+ function sensitiveKind(kind) {
50
+ return kind === "password" || kind === "one-time code";
51
+ }
52
+ /** Most fields read in one frame; a page with more is not a form anyone signs in with. */
53
+ const MAX_FIELDS = 500;
54
+ /** Every input and textarea of one frame with a value, open shadow roots included. */
55
+ function readFrame(frame) {
56
+ return frame.evaluate((max) => {
57
+ const out = [];
58
+ const skip = new Set(["checkbox", "radio", "submit", "button", "reset", "image", "file", "range", "color"]);
59
+ const walk = (root) => {
60
+ for (const el of Array.from(root.querySelectorAll("*"))) {
61
+ if (out.length >= max)
62
+ return;
63
+ if (el.shadowRoot)
64
+ walk(el.shadowRoot);
65
+ if (el.tagName !== "INPUT" && el.tagName !== "TEXTAREA")
66
+ continue;
67
+ const field = el;
68
+ const type = (field.type || "").toLowerCase();
69
+ if (!field.value || skip.has(type))
70
+ continue;
71
+ // The ref Playwright's snapshot gave this element, so the host can mask that line.
72
+ const ref = el._ariaRef?.ref;
73
+ out.push({
74
+ type,
75
+ autocomplete: field.getAttribute("autocomplete") ?? "",
76
+ name: field.getAttribute("name") ?? "",
77
+ id: field.id,
78
+ value: field.value,
79
+ ...(typeof ref === "string" ? { ref } : {}),
80
+ });
81
+ }
82
+ };
83
+ walk(document);
84
+ return out;
85
+ }, MAX_FIELDS);
86
+ }
87
+ /**
88
+ * The inputs with a value in every frame of `page` and the kind of each: one evaluate per
89
+ * frame, in parallel. A frame that cannot be read (navigating, detached) is skipped.
90
+ */
91
+ export async function pageFields(page) {
92
+ const frames = await Promise.all(page.frames().map((f) => readFrame(f).catch(() => [])));
93
+ return frames.flat().map((f) => {
94
+ const kind = fieldKind(f);
95
+ return kind ? { ...f, kind } : f;
96
+ });
97
+ }
98
+ /** The sensitive fields (`sensitiveKind`) of `page` that hold a value. */
99
+ export async function sensitiveFields(page) {
100
+ return (await pageFields(page)).filter((f) => sensitiveKind(f.kind));
101
+ }
102
+ const REF = /^(f\d+)?e\d+$/;
103
+ /**
104
+ * An aria snapshot (`mode: "ai"`) with the value of each element in `refs` replaced by
105
+ * `SENSITIVE_MARK`: `- textbox "Password" [ref=e6]: hunter2` reads
106
+ * `- textbox "Password" [ref=e6]: [sensitive field]`, whatever the length of the value.
107
+ */
108
+ export function maskSnapshot(text, refs) {
109
+ if (!refs.size || !text)
110
+ return text;
111
+ return text.replace(/^(\s*- [^\n]*?\[ref=((?:f\d+)?e\d+)\](?: \[[^\]\n]*\])*):( .*)?$/gm, (line, head, ref, value) => refs.has(ref) && value !== undefined ? `${head}: ${SENSITIVE_MARK}` : line);
112
+ }
113
+ /** The same masking on the JSON form of an aria snapshot (`ariaSnapshotJSON`). */
114
+ export function maskSnapshotJSON(json, refs) {
115
+ if (!refs.size)
116
+ return json;
117
+ const walk = (node) => {
118
+ if (Array.isArray(node))
119
+ return node.map(walk);
120
+ if (!node || typeof node !== "object")
121
+ return node;
122
+ const n = node;
123
+ const out = { ...n };
124
+ const masked = typeof n.ref === "string" && refs.has(n.ref);
125
+ if (masked) {
126
+ if ("text" in n)
127
+ out.text = SENSITIVE_MARK;
128
+ if ("value" in n)
129
+ out.value = SENSITIVE_MARK;
130
+ }
131
+ if (Array.isArray(n.children))
132
+ out.children = n.children.map((c) => (masked && typeof c === "string" ? SENSITIVE_MARK : walk(c)));
133
+ return out;
134
+ };
135
+ return walk(json);
136
+ }
137
+ /** The refs of the sensitive fields among `fields`. */
138
+ export function sensitiveRefs(fields) {
139
+ return new Set(fields.filter((f) => sensitiveKind(f.kind) && f.ref && REF.test(f.ref)).map((f) => f.ref));
140
+ }
141
+ /**
142
+ * Makes every aria snapshot of `page` mask its sensitive fields: Playwright MCP takes the page
143
+ * snapshot of a tool result with `page.ariaSnapshot` (or `ariaSnapshotJSON` in JSON mode), and
144
+ * writes it to a file or puts it in the result right after. The fields are read after the
145
+ * snapshot, so the refs are the ones it just gave; `onFields` hears them first (the host's
146
+ * redactor learns the values, for the rest of the result). Undone with the returned function.
147
+ */
148
+ export function maskSnapshots(page, onFields) {
149
+ const target = page;
150
+ const text = target.ariaSnapshot;
151
+ const json = target.ariaSnapshotJSON;
152
+ const read = async () => {
153
+ const fields = await sensitiveFields(page).catch(() => []);
154
+ if (fields.length)
155
+ onFields(fields);
156
+ return sensitiveRefs(fields);
157
+ };
158
+ target.ariaSnapshot = async (options) => {
159
+ const out = (await text.call(page, options));
160
+ return maskSnapshot(out, await read());
161
+ };
162
+ if (json)
163
+ target.ariaSnapshotJSON = async (options) => {
164
+ const out = await json.call(page, options);
165
+ return maskSnapshotJSON(out, await read());
166
+ };
167
+ return () => {
168
+ target.ariaSnapshot = text;
169
+ if (json)
170
+ target.ariaSnapshotJSON = json;
171
+ };
172
+ }
173
+ /** Keys that put a character into the focused field (`a`, `Shift+A`), not `Enter` or `Tab`. */
174
+ function typesCharacter(key) {
175
+ if (typeof key !== "string")
176
+ return false;
177
+ const last = key.split("+").pop() ?? "";
178
+ return last.length === 1 && !/^(Control|Meta|Alt)\+/i.test(key);
179
+ }
180
+ async function targetInfo(page, target) {
181
+ const locator = page.locator(REF.test(target) ? `aria-ref=${target}` : target);
182
+ return await locator
183
+ .evaluate((el) => ({
184
+ type: (el.type || "").toLowerCase(),
185
+ autocomplete: el.getAttribute("autocomplete") ?? "",
186
+ name: el.getAttribute("name") ?? "",
187
+ id: el.id,
188
+ }), undefined, { timeout: 2_000 })
189
+ .catch(() => undefined);
190
+ }
191
+ /** The focused element of a frame, through open shadow roots; undefined when the frame has no focus. */
192
+ function focusedInfo(frame) {
193
+ return frame.evaluate(() => {
194
+ if (!document.hasFocus())
195
+ return undefined;
196
+ let el = document.activeElement;
197
+ while (el?.shadowRoot?.activeElement)
198
+ el = el.shadowRoot.activeElement;
199
+ if (!el || (el.tagName !== "INPUT" && el.tagName !== "TEXTAREA"))
200
+ return undefined;
201
+ return {
202
+ type: (el.type || "").toLowerCase(),
203
+ autocomplete: el.getAttribute("autocomplete") ?? "",
204
+ name: el.getAttribute("name") ?? "",
205
+ id: el.id,
206
+ };
207
+ });
208
+ }
209
+ /** The stock tools that type text, and the arguments that say where. */
210
+ export const TYPING_TOOLS = new Set([
211
+ "browser_type",
212
+ "browser_fill_form",
213
+ "browser_press_key",
214
+ "browser_press_sequentially",
215
+ "browser_keydown",
216
+ ]);
217
+ /**
218
+ * The kind of sensitive field a typing call would put text into, or undefined. A target the
219
+ * page cannot resolve counts as not sensitive: the call then fails the same way.
220
+ */
221
+ export async function typesIntoSensitive(page, tool, args) {
222
+ const targets = [];
223
+ if (tool === "browser_type") {
224
+ if (typeof args.target === "string" && typeof args.text === "string" && args.text)
225
+ targets.push(args.target);
226
+ }
227
+ else if (tool === "browser_fill_form") {
228
+ if (Array.isArray(args.fields))
229
+ for (const f of args.fields)
230
+ if (f.type === "textbox" && typeof f.target === "string" && typeof f.value === "string" && f.value)
231
+ targets.push(f.target);
232
+ }
233
+ else if (tool === "browser_press_sequentially" ? typeof args.text === "string" && args.text : typesCharacter(args.key)) {
234
+ for (const frame of page.frames()) {
235
+ const kind = fieldKind((await focusedInfo(frame).catch(() => undefined)) ?? { type: "", autocomplete: "", name: "", id: "" });
236
+ if (sensitiveKind(kind))
237
+ return kind;
238
+ }
239
+ return undefined;
240
+ }
241
+ for (const target of targets) {
242
+ const info = await targetInfo(page, target);
243
+ const kind = info ? fieldKind(info) : undefined;
244
+ if (sensitiveKind(kind))
245
+ return kind;
246
+ }
247
+ return undefined;
248
+ }
249
+ /** The error of a typing call into a sensitive field. */
250
+ export function sensitiveRefusal(tool, kind) {
251
+ return `${tool} was refused: that field takes a ${kind}, and the agent never types one. Ask the person to type it (with browser_request_human, if this server offers it), or sign in with browser_login and a vault entry for this site; a flow replay can type one passed as keychain:<item>.`;
252
+ }
253
+ /**
254
+ * The values `browser_type` or `browser_fill_form` would put into secret fields (`secretField`),
255
+ * so a recording can stop its trace first.
256
+ */
257
+ export async function secretValues(page, tool, args) {
258
+ const pairs = tool === "browser_type"
259
+ ? [[args.target, args.text]]
260
+ : tool === "browser_fill_form" && Array.isArray(args.fields)
261
+ ? args.fields
262
+ .filter((f) => f.type === "textbox")
263
+ .map((f) => [f.target, f.value])
264
+ : [];
265
+ const out = [];
266
+ for (const [target, value] of pairs) {
267
+ if (typeof target !== "string" || typeof value !== "string" || !value)
268
+ continue;
269
+ const info = await targetInfo(page, target);
270
+ if (info && secretField(info))
271
+ out.push(value);
272
+ }
273
+ return out;
274
+ }
275
+ //# sourceMappingURL=sensitive.js.map
package/dist/session.d.ts CHANGED
@@ -5,6 +5,13 @@
5
5
  * keys each session's backend and tab locks on it (`sharing.ts`).
6
6
  */
7
7
  export declare const SESSION_META_KEY = "io.turno/session";
8
+ /**
9
+ * The name of the agent a relayed call comes from (the client's `clientInfo.name`, like
10
+ * "claude-code" or "codex-mcp-client"). mcpd puts it next to the session id when it knows it, so
11
+ * the agent cursor names each session's agent, not mcpd. A server talking to a client directly
12
+ * uses that client's own name instead.
13
+ */
14
+ export declare const CLIENT_META_KEY = "io.turno/client";
8
15
  /**
9
16
  * The experimental capability a server declares in `initialize` to hear when a client session
10
17
  * ends: mcpd then sends it `SESSION_ENDED_METHOD` with `{ session: <the id above> }` for each
@@ -18,3 +25,8 @@ export declare const SESSION_ENDED_METHOD = "notifications/io.turno/session_ende
18
25
  * printable string (a client talking to the server directly may send anything there).
19
26
  */
20
27
  export declare function sessionFromMeta(meta: unknown): string | undefined;
28
+ /**
29
+ * The client name in a request's `_meta` (`CLIENT_META_KEY`), or undefined when there is none
30
+ * or it is not a short printable string.
31
+ */
32
+ export declare function clientFromMeta(meta: unknown): string | undefined;
package/dist/session.js CHANGED
@@ -5,6 +5,13 @@
5
5
  * keys each session's backend and tab locks on it (`sharing.ts`).
6
6
  */
7
7
  export const SESSION_META_KEY = "io.turno/session";
8
+ /**
9
+ * The name of the agent a relayed call comes from (the client's `clientInfo.name`, like
10
+ * "claude-code" or "codex-mcp-client"). mcpd puts it next to the session id when it knows it, so
11
+ * the agent cursor names each session's agent, not mcpd. A server talking to a client directly
12
+ * uses that client's own name instead.
13
+ */
14
+ export const CLIENT_META_KEY = "io.turno/client";
8
15
  /**
9
16
  * The experimental capability a server declares in `initialize` to hear when a client session
10
17
  * ends: mcpd then sends it `SESSION_ENDED_METHOD` with `{ session: <the id above> }` for each
@@ -27,4 +34,21 @@ export function sessionFromMeta(meta) {
27
34
  return undefined;
28
35
  return /^[\x21-\x7e]+$/.test(value) ? value : undefined;
29
36
  }
37
+ /** Longest client name accepted. */
38
+ const MAX_CLIENT = 64;
39
+ /**
40
+ * The client name in a request's `_meta` (`CLIENT_META_KEY`), or undefined when there is none
41
+ * or it is not a short printable string.
42
+ */
43
+ export function clientFromMeta(meta) {
44
+ if (typeof meta !== "object" || meta === null)
45
+ return undefined;
46
+ const value = meta[CLIENT_META_KEY];
47
+ if (typeof value !== "string")
48
+ return undefined;
49
+ const name = value.trim();
50
+ if (name.length === 0 || name.length > MAX_CLIENT)
51
+ return undefined;
52
+ return /^[\x20-\x7e]+$/.test(name) ? name : undefined;
53
+ }
30
54
  //# sourceMappingURL=session.js.map
@@ -48,6 +48,9 @@ import { type ProxySettings, type UserAgentMode } from "./network.js";
48
48
  * - `userAgent`, `proxy` (format 11), and the `"camoufox"` value of `engine`: opt-in network and
49
49
  * user agent settings (`network.ts`) and Camoufox as an alternate engine
50
50
  * (`engine-camoufox.ts`), all off by default.
51
+ * - `cursor` (format 12): the agent cursor (`agent-cursor.ts`): `"auto"` (the default) draws it
52
+ * when someone can see the browser (a Chrome window, or the live view), `"on"` always, `"off"`
53
+ * never.
51
54
  *
52
55
  * A missing file means Chrome's own defaults, as before identity.json existed.
53
56
  */
@@ -58,7 +61,7 @@ import { type ProxySettings, type UserAgentMode } from "./network.js";
58
61
  * only when it uses one of them, so an older turno-browser keeps reading every other file and
59
62
  * refuses one it would misread with "update turno-browser".
60
63
  */
61
- export declare const IDENTITY_FORMAT_VERSION = 11;
64
+ export declare const IDENTITY_FORMAT_VERSION = 12;
62
65
  /** The keys format 2 added. */
63
66
  declare const FORMAT_2_KEYS: readonly ["tabs", "backgroundThrottling", "settle", "block", "cache"];
64
67
  /** The keys format 3 added. */
@@ -94,6 +97,11 @@ export declare const MIN_LIVE_WAIT_MS = 5000;
94
97
  export declare const MAX_LIVE_WAIT_MS: number;
95
98
  /** The keys format 11 added (the `"camoufox"` engine also writes format 11). */
96
99
  declare const FORMAT_11_KEYS: readonly ["userAgent", "proxy"];
100
+ /** The keys format 12 added. */
101
+ declare const FORMAT_12_KEYS: readonly ["cursor"];
102
+ /** The values of `cursor` (the agent cursor, `agent-cursor.ts`). */
103
+ export declare const CURSOR_MODES: readonly ["auto", "on", "off"];
104
+ export type CursorMode = (typeof CURSOR_MODES)[number];
97
105
  /** The values of `engine`: `"chrome"` (the default), read mode, and Camoufox (format 11). */
98
106
  declare const ENGINE_VALUES: readonly ["chrome", "lightpanda", "camoufox"];
99
107
  /** What turno-browser records for an identity (`recorder.ts`, `recordings.ts`); all off by default. */
@@ -182,13 +190,15 @@ export interface IdentitySettings {
182
190
  userAgent?: UserAgentMode;
183
191
  /** A proxy for the identity's traffic; credentials only as `keychain:` references. */
184
192
  proxy?: ProxySettings;
193
+ /** The agent cursor: `"auto"` (the default, when the browser can be seen), `"on"` or `"off"`. */
194
+ cursor?: CursorMode;
185
195
  /** ISO dates. */
186
196
  created: string;
187
197
  updated: string;
188
198
  }
189
199
  /** A change to identity.json: a value sets the key, `null` removes it. */
190
200
  export type SettingsPatch = {
191
- [K in "timezone" | "locale" | "languages" | "region" | "health" | (typeof FORMAT_2_KEYS)[number] | (typeof FORMAT_3_KEYS)[number] | (typeof FORMAT_4_KEYS)[number] | (typeof FORMAT_5_KEYS)[number] | (typeof FORMAT_6_KEYS)[number] | (typeof FORMAT_7_KEYS)[number] | (typeof FORMAT_8_KEYS)[number] | (typeof FORMAT_9_KEYS)[number] | (typeof FORMAT_10_KEYS)[number] | (typeof FORMAT_11_KEYS)[number]]?: IdentitySettings[K] | null;
201
+ [K in "timezone" | "locale" | "languages" | "region" | "health" | (typeof FORMAT_2_KEYS)[number] | (typeof FORMAT_3_KEYS)[number] | (typeof FORMAT_4_KEYS)[number] | (typeof FORMAT_5_KEYS)[number] | (typeof FORMAT_6_KEYS)[number] | (typeof FORMAT_7_KEYS)[number] | (typeof FORMAT_8_KEYS)[number] | (typeof FORMAT_9_KEYS)[number] | (typeof FORMAT_10_KEYS)[number] | (typeof FORMAT_11_KEYS)[number] | (typeof FORMAT_12_KEYS)[number]]?: IdentitySettings[K] | null;
192
202
  };
193
203
  /**
194
204
  * The Chrome switches to drop for this identity's keychain setting, as Playwright launch
package/dist/settings.js CHANGED
@@ -54,6 +54,9 @@ import { parseDuration, parseSize } from "./units.js";
54
54
  * - `userAgent`, `proxy` (format 11), and the `"camoufox"` value of `engine`: opt-in network and
55
55
  * user agent settings (`network.ts`) and Camoufox as an alternate engine
56
56
  * (`engine-camoufox.ts`), all off by default.
57
+ * - `cursor` (format 12): the agent cursor (`agent-cursor.ts`): `"auto"` (the default) draws it
58
+ * when someone can see the browser (a Chrome window, or the live view), `"on"` always, `"off"`
59
+ * never.
57
60
  *
58
61
  * A missing file means Chrome's own defaults, as before identity.json existed.
59
62
  */
@@ -64,7 +67,7 @@ import { parseDuration, parseSize } from "./units.js";
64
67
  * only when it uses one of them, so an older turno-browser keeps reading every other file and
65
68
  * refuses one it would misread with "update turno-browser".
66
69
  */
67
- export const IDENTITY_FORMAT_VERSION = 11;
70
+ export const IDENTITY_FORMAT_VERSION = 12;
68
71
  /** The keys format 2 added. */
69
72
  const FORMAT_2_KEYS = ["tabs", "backgroundThrottling", "settle", "block", "cache"];
70
73
  /** The keys format 3 added. */
@@ -92,6 +95,10 @@ export const MIN_LIVE_WAIT_MS = 5_000;
92
95
  export const MAX_LIVE_WAIT_MS = 30 * 60_000;
93
96
  /** The keys format 11 added (the `"camoufox"` engine also writes format 11). */
94
97
  const FORMAT_11_KEYS = ["userAgent", "proxy"];
98
+ /** The keys format 12 added. */
99
+ const FORMAT_12_KEYS = ["cursor"];
100
+ /** The values of `cursor` (the agent cursor, `agent-cursor.ts`). */
101
+ export const CURSOR_MODES = ["auto", "on", "off"];
95
102
  /** The values of `engine`: `"chrome"` (the default), read mode, and Camoufox (format 11). */
96
103
  const ENGINE_VALUES = ["chrome", "lightpanda", "camoufox"];
97
104
  /** Recordings size cap bounds. */
@@ -122,6 +129,7 @@ const KEYS = new Set([
122
129
  ...FORMAT_9_KEYS,
123
130
  ...FORMAT_10_KEYS,
124
131
  ...FORMAT_11_KEYS,
132
+ ...FORMAT_12_KEYS,
125
133
  "created",
126
134
  "updated",
127
135
  ]);
@@ -199,6 +207,8 @@ function browserProblems(v, out) {
199
207
  humanizeProblems(v.humanize, out);
200
208
  if (v.sharing !== undefined && v.sharing !== "session" && v.sharing !== "tabs")
201
209
  out.push('sharing must be "session" (the default, one agent session at a time) or "tabs"');
210
+ if (v.cursor !== undefined && !CURSOR_MODES.includes(v.cursor))
211
+ out.push('cursor must be "auto" (the default, when the browser can be seen), "on" or "off"');
202
212
  engineProblems(v, out);
203
213
  recordProblems(v, out);
204
214
  actProblems(v.act, out);
@@ -469,6 +479,7 @@ export function writeIdentitySettings(id, patch, env = process.env, now = new Da
469
479
  next[key] = value;
470
480
  }
471
481
  const formats = [
482
+ FORMAT_12_KEYS,
472
483
  FORMAT_11_KEYS,
473
484
  FORMAT_10_KEYS,
474
485
  FORMAT_9_KEYS,
@@ -481,7 +492,8 @@ export function writeIdentitySettings(id, patch, env = process.env, now = new Da
481
492
  FORMAT_2_KEYS,
482
493
  ];
483
494
  // Camoufox is an engine value, not a key: it writes format 11, so an older turno-browser refuses it.
484
- const newest = next.engine === "camoufox" ? 0 : formats.findIndex((keys) => keys.some((k) => next[k] !== undefined));
495
+ const found = formats.findIndex((keys) => keys.some((k) => next[k] !== undefined));
496
+ const newest = next.engine === "camoufox" && (found < 0 || found > 1) ? 1 : found;
485
497
  next.version = newest < 0 ? 1 : IDENTITY_FORMAT_VERSION - newest;
486
498
  if (typeof next.locale === "string")
487
499
  next.locale = canonicalLocale(next.locale) ?? next.locale;
package/dist/tools.d.ts CHANGED
@@ -26,9 +26,12 @@ export interface StockAccess {
26
26
  /**
27
27
  * Runs a stock tool the way a call of its own runs (tab governor, click diagnosis); with
28
28
  * `snapshot: false` the result leaves out the page snapshot an action would add.
29
+ * `fromSecretStore` says the text typed was read from the secret store (a flow replay's
30
+ * `keychain:` parameter), so it may go into a password or one-time code field.
29
31
  */
30
32
  call(name: string, args: Record<string, unknown>, options: {
31
33
  snapshot: boolean;
34
+ fromSecretStore?: boolean;
32
35
  }): Promise<ToolResult>;
33
36
  /** URL and title of the current tab, when there is one. */
34
37
  page(): Promise<{
@@ -71,6 +74,8 @@ interface TurnoToolContext {
71
74
  engine?: string;
72
75
  /** Providers that replace the configured ones (tests inject fakes). */
73
76
  providers?: Providers;
77
+ /** Runs a person step on the session's tab (`browser_request_human`); set by the host for it. */
78
+ human?: (params: Record<string, unknown>) => Promise<ToolResult>;
74
79
  }
75
80
  /** Stand-ins for the opt-in providers: a model for natural language actions, a captcha solver. */
76
81
  export interface Providers {
package/dist/tools.js CHANGED
@@ -1,12 +1,20 @@
1
1
  import { actTool, extractTool, observeTool } from "./act.js";
2
2
  import { batchTool } from "./batch.js";
3
3
  import { solveCaptchaTool } from "./captcha.js";
4
+ import { requestHumanTool } from "./human-step.js";
4
5
  import { loginTool } from "./login-tool.js";
5
6
  import { recordTool } from "./recorder.js";
6
7
  import { flowsTool, replayTool } from "./replay.js";
7
8
  import { upstream, } from "./upstream.js";
8
9
  /** The tools turno adds to every session. */
9
- export const TURNO_TOOLS = [batchTool(), loginTool(), recordTool(), replayTool(), flowsTool()];
10
+ export const TURNO_TOOLS = [
11
+ batchTool(),
12
+ loginTool(),
13
+ recordTool(),
14
+ replayTool(),
15
+ flowsTool(),
16
+ requestHumanTool(),
17
+ ];
10
18
  /**
11
19
  * The tools an identity lists only after the person turns their feature on in identity.json
12
20
  * (format 8): natural language actions (`act`) and captcha solving (`captcha`). Off, they are
package/dist/tuning.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { HumanizeLevel, HumanizeSettings } from "./humanize.js";
2
2
  import { type ResourcePolicy } from "./resources.js";
3
- import type { IdentitySettings } from "./settings.js";
3
+ import type { CursorMode, IdentitySettings } from "./settings.js";
4
4
  import type { SharingMode } from "./sharing.js";
5
5
  import type { TabLockPolicy } from "./tab-locks.js";
6
6
  /**
@@ -43,6 +43,8 @@ export interface Tuning {
43
43
  sharing: SharingMode;
44
44
  /** With `"sharing": "tabs"`: the lock wait and idle release of identity.json `tabLocks`. */
45
45
  tabLocks: Partial<TabLockPolicy>;
46
+ /** The agent cursor (`agent-cursor.ts`), from `--cursor` or identity.json `cursor`; `"auto"` by default. */
47
+ cursor: CursorMode;
46
48
  }
47
49
  /** The defaults, documented on the browser identities page. */
48
50
  export declare const DEFAULT_TABS: Readonly<TabPolicy>;
@@ -55,6 +57,7 @@ export interface TuningFlags {
55
57
  backgroundThrottling?: boolean;
56
58
  humanize?: HumanizeLevel;
57
59
  sharing?: SharingMode;
60
+ cursor?: CursorMode;
58
61
  }
59
62
  /** The tuning of a session: flags, then identity.json, then the defaults. */
60
63
  export declare function resolveTuning(settings: IdentitySettings | undefined, flags?: TuningFlags): Tuning;
package/dist/tuning.js CHANGED
@@ -28,6 +28,7 @@ export function resolveTuning(settings, flags = {}) {
28
28
  level: flags.humanize ?? settings?.humanize?.level ?? "off",
29
29
  },
30
30
  sharing: flags.sharing ?? settings?.sharing ?? "session",
31
+ cursor: flags.cursor ?? settings?.cursor ?? "auto",
31
32
  tabLocks: {
32
33
  ...(settings?.tabLocks?.wait === undefined ? {} : { waitMs: ms(settings.tabLocks.wait) }),
33
34
  ...(settings?.tabLocks?.release === undefined ? {} : { releaseMs: ms(settings.tabLocks.release) }),
@@ -120,6 +120,11 @@ export interface UpstreamContext {
120
120
  newTab(): Promise<UpstreamTab>;
121
121
  /** Points the stock tools at a tab without bringing it to the front (`"sharing": "tabs"`). */
122
122
  _setCurrentTab(tab: UpstreamTab | undefined): void;
123
+ /**
124
+ * What upstream passes every text result, written file and session log line through (its own
125
+ * `secrets` config). The host chains its redactor here, so a file a tool writes is redacted too.
126
+ */
127
+ redactSecrets(text: string): string;
123
128
  }
124
129
  /**
125
130
  * The tabs of a `BrowserBackend`, for the tab governor: `initialize` builds the
@@ -0,0 +1,60 @@
1
+ import type { Page } from "patchright-core";
2
+ import { PauseGate, type PauseHold, type TabState } from "./live.js";
3
+ import type { LiveBrowser } from "./live-server.js";
4
+ /**
5
+ * What the host holds calls with and compares the tabs by: the pause gate of one browser, the
6
+ * tab each session worked on last, and the calls in flight. With the live view on it is the live
7
+ * server (`live-server.ts`), which also streams the page and takes the user's own pause. Without
8
+ * it, a `PlainWatch` does the same for the pauses a call can start itself: a person step
9
+ * (`browser_request_human`) holds every session of the browser while the person acts.
10
+ */
11
+ export interface BrowserWatch {
12
+ readonly gate: PauseGate;
13
+ readonly paused: boolean;
14
+ /** How long a call held by the user's own pause waits. */
15
+ readonly waitMs: number;
16
+ /** Agent calls running now. */
17
+ readonly inFlight: number;
18
+ /** A browser launched; returns what to call when it goes away. */
19
+ bind(browser: LiveBrowser): () => void;
20
+ /** The page a call of `session` worked on. */
21
+ follow(session: string, page: Page | undefined): void;
22
+ /** The page the last call of `session` worked on (it may have closed since). */
23
+ lastPage(session: string): Page | undefined;
24
+ /** The id the notes give a tab. */
25
+ idOf(page: Page): number;
26
+ /** The tabs now, as the notes compare them. */
27
+ tabStates(): Promise<TabState[]>;
28
+ /** An agent call starts; returns what to call when it ends. */
29
+ begin(): () => void;
30
+ /** Starts a pause (false when one is on); `front` brings the shown tab to the front. */
31
+ pause(by: string, front?: boolean, hold?: PauseHold): Promise<boolean>;
32
+ /** Ends the pause and lets the held calls go; false when there was none. */
33
+ resume(): boolean;
34
+ }
35
+ /** The tab's title, or "" when the page does not answer within a second. */
36
+ export declare function titleOf(page: Page): Promise<string>;
37
+ /** The watch of a browser without the live view: no stream, no socket, no user pause. */
38
+ export declare class PlainWatch implements BrowserWatch {
39
+ readonly waitMs: number;
40
+ readonly gate: PauseGate;
41
+ private browser;
42
+ private heldBrowser;
43
+ private readonly lastBySession;
44
+ private readonly ids;
45
+ private nextId;
46
+ private busy;
47
+ constructor(waitMs?: number);
48
+ get paused(): boolean;
49
+ get inFlight(): number;
50
+ bind(browser: LiveBrowser): () => void;
51
+ follow(session: string, page: Page | undefined): void;
52
+ lastPage(session: string): Page | undefined;
53
+ idOf(page: Page): number;
54
+ /** The agent's pages: every page, or in attach mode only those the agent worked on. */
55
+ private pages;
56
+ tabStates(): Promise<TabState[]>;
57
+ begin(): () => void;
58
+ pause(by: string, _front?: boolean, hold?: PauseHold): Promise<boolean>;
59
+ resume(): boolean;
60
+ }