turno-browser 0.3.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 (94) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +32 -3
  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 +29 -2
  8. package/dist/api.js +29 -2
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/batch.d.ts +5 -0
  12. package/dist/batch.js +3 -3
  13. package/dist/bin/mcp.js +58 -1
  14. package/dist/captcha.d.ts +77 -0
  15. package/dist/captcha.js +333 -0
  16. package/dist/cdp-relay.d.ts +20 -0
  17. package/dist/cdp-relay.js +101 -0
  18. package/dist/chrome-features.d.ts +23 -0
  19. package/dist/chrome-features.js +44 -0
  20. package/dist/diagnose.d.ts +7 -0
  21. package/dist/diagnose.js +61 -6
  22. package/dist/doctor.d.ts +37 -3
  23. package/dist/doctor.js +230 -5
  24. package/dist/engine-attach.d.ts +27 -0
  25. package/dist/engine-attach.js +165 -0
  26. package/dist/engine-camoufox.d.ts +32 -0
  27. package/dist/engine-camoufox.js +270 -0
  28. package/dist/engine-lightpanda.d.ts +72 -0
  29. package/dist/engine-lightpanda.js +292 -0
  30. package/dist/engine.d.ts +63 -11
  31. package/dist/engine.js +104 -28
  32. package/dist/flows.d.ts +127 -0
  33. package/dist/flows.js +294 -0
  34. package/dist/governor.d.ts +42 -7
  35. package/dist/governor.js +82 -32
  36. package/dist/host.d.ts +17 -2
  37. package/dist/host.js +618 -41
  38. package/dist/human-input.d.ts +84 -0
  39. package/dist/human-input.js +443 -0
  40. package/dist/humanize.d.ts +123 -0
  41. package/dist/humanize.js +241 -0
  42. package/dist/identities.js +2 -0
  43. package/dist/idle-timer.d.ts +12 -0
  44. package/dist/idle-timer.js +25 -0
  45. package/dist/index.d.ts +8 -3
  46. package/dist/index.js +5 -1
  47. package/dist/lifecycle.d.ts +9 -1
  48. package/dist/lifecycle.js +9 -1
  49. package/dist/live-client.d.ts +22 -0
  50. package/dist/live-client.js +93 -0
  51. package/dist/live-page.d.ts +11 -0
  52. package/dist/live-page.js +143 -0
  53. package/dist/live-server.d.ts +173 -0
  54. package/dist/live-server.js +640 -0
  55. package/dist/live.d.ts +120 -0
  56. package/dist/live.js +203 -0
  57. package/dist/login-tool.d.ts +13 -0
  58. package/dist/login-tool.js +5 -1
  59. package/dist/login.d.ts +4 -1
  60. package/dist/login.js +11 -2
  61. package/dist/network-chrome.d.ts +74 -0
  62. package/dist/network-chrome.js +178 -0
  63. package/dist/network.d.ts +125 -0
  64. package/dist/network.js +263 -0
  65. package/dist/opt-in-settings.d.ts +69 -0
  66. package/dist/opt-in-settings.js +151 -0
  67. package/dist/recorder.d.ts +88 -0
  68. package/dist/recorder.js +538 -0
  69. package/dist/recordings.d.ts +116 -0
  70. package/dist/recordings.js +474 -0
  71. package/dist/redact.d.ts +7 -0
  72. package/dist/redact.js +18 -0
  73. package/dist/replay.d.ts +20 -0
  74. package/dist/replay.js +382 -0
  75. package/dist/reputation.d.ts +24 -2
  76. package/dist/reputation.js +63 -17
  77. package/dist/session-export.js +1 -1
  78. package/dist/session.d.ts +10 -2
  79. package/dist/session.js +10 -2
  80. package/dist/settings.d.ts +104 -2
  81. package/dist/settings.js +204 -6
  82. package/dist/sharing.d.ts +96 -0
  83. package/dist/sharing.js +269 -0
  84. package/dist/snippet.d.ts +8 -2
  85. package/dist/snippet.js +10 -4
  86. package/dist/tab-locks.d.ts +63 -0
  87. package/dist/tab-locks.js +179 -0
  88. package/dist/tools.d.ts +38 -0
  89. package/dist/tools.js +20 -1
  90. package/dist/tuning.d.ts +14 -0
  91. package/dist/tuning.js +9 -0
  92. package/dist/upstream.d.ts +11 -0
  93. package/npm-shrinkwrap.json +2 -2
  94. package/package.json +1 -1
@@ -1,3 +1,6 @@
1
+ import { type ActSettings, type CaptchaSettings } from "./opt-in-settings.js";
2
+ import { type HumanizeSettings } from "./humanize.js";
3
+ import { type ProxySettings, type UserAgentMode } from "./network.js";
1
4
  /**
2
5
  * identity.json: what stays fixed for one browser identity, so a site sees the same person in
3
6
  * the same place every time. It sits next to the Chrome profile directory
@@ -22,6 +25,29 @@
22
25
  * `"mock"` (the default, also when the key is missing) keeps Playwright's
23
26
  * `--use-mock-keychain` and `--password-store=basic`, a fixed public key; `"system"` drops
24
27
  * them, so Chrome uses the macOS Keychain or the Linux Secret Service.
28
+ * - `humanize` (format 4): human-like pointer, typing and scrolling (`humanize.ts`), off by default.
29
+ * - `sharing` (format 5): `"session"` (the default) serves one agent session at a time;
30
+ * `"tabs"` lets several sessions use the browser at once, each in its own locked tabs
31
+ * (`sharing.ts`; mcp.toml then runs the server with `exclusive = false`).
32
+ * - `engine`, `attach` (format 6): which engine runs the identity (`engine.ts`). `engine:
33
+ * "lightpanda"` is read mode; `attach` connects to a Chrome the user already has open
34
+ * (`"auto"`, a user data dir, or a loopback endpoint). Both off by default.
35
+ * - `record` (format 7): what turno-browser records for this identity, all off by default:
36
+ * `flows` (every session's actions as a flow, `recorder.ts`), `traces` (Playwright traces) and
37
+ * `screenshots` (one per action), the last two under the identity's state folder with a
38
+ * size cap (`maxSize`, default 200MB) and the oldest recordings removed first (`recordings.ts`).
39
+ * - `act`, `captcha` (format 8): natural language actions and captcha solving, both off by
40
+ * default and both sending page content to a model or a solver the user picks
41
+ * (`opt-in-settings.ts`). Keys are `keychain:` references, never values.
42
+ * - `tabLocks` (format 9): with `"sharing": "tabs"`, how long a call waits for a tab another
43
+ * session holds (`wait`, default 10s) and how long a session without calls keeps its tabs
44
+ * (`release`, default 5m) (`tab-locks.ts`). No effect with `"sharing": "session"`.
45
+ * - `live` (format 10): the live view and take-over (`live.ts`), off by default: `enabled` serves
46
+ * a view of the agent's tab on 127.0.0.1 and lets the user pause the agent; `wait` is how long
47
+ * a paused call waits for the user to resume before it fails (default 2m).
48
+ * - `userAgent`, `proxy` (format 11), and the `"camoufox"` value of `engine`: opt-in network and
49
+ * user agent settings (`network.ts`) and Camoufox as an alternate engine
50
+ * (`engine-camoufox.ts`), all off by default.
25
51
  *
26
52
  * A missing file means Chrome's own defaults, as before identity.json existed.
27
53
  */
@@ -32,11 +58,57 @@
32
58
  * only when it uses one of them, so an older turno-browser keeps reading every other file and
33
59
  * refuses one it would misread with "update turno-browser".
34
60
  */
35
- export declare const IDENTITY_FORMAT_VERSION = 3;
61
+ export declare const IDENTITY_FORMAT_VERSION = 11;
36
62
  /** The keys format 2 added. */
37
63
  declare const FORMAT_2_KEYS: readonly ["tabs", "backgroundThrottling", "settle", "block", "cache"];
38
64
  /** The keys format 3 added. */
39
65
  declare const FORMAT_3_KEYS: readonly ["keychain"];
66
+ /** The keys format 4 added. */
67
+ declare const FORMAT_4_KEYS: readonly ["humanize"];
68
+ /** The keys format 5 added. */
69
+ declare const FORMAT_5_KEYS: readonly ["sharing"];
70
+ /** The keys format 6 added. */
71
+ declare const FORMAT_6_KEYS: readonly ["engine", "attach"];
72
+ /** The keys format 7 added. */
73
+ declare const FORMAT_7_KEYS: readonly ["record"];
74
+ /** The keys format 8 added. */
75
+ declare const FORMAT_8_KEYS: readonly ["act", "captcha"];
76
+ /** The keys format 9 added. */
77
+ declare const FORMAT_9_KEYS: readonly ["tabLocks"];
78
+ /** With `"sharing": "tabs"`: the lock wait and the idle release, as durations. */
79
+ export interface TabLockSettings {
80
+ wait?: string;
81
+ release?: string;
82
+ }
83
+ /** The keys format 10 added. */
84
+ declare const FORMAT_10_KEYS: readonly ["live"];
85
+ /** The live view and take-over (`live.ts`); off by default. */
86
+ export interface LiveSettings {
87
+ /** Serve the live view and let the user pause the agent. */
88
+ enabled?: boolean;
89
+ /** How long a paused call waits for the user, like `"2m"` (from `"5s"` to `"30m"`). */
90
+ wait?: string;
91
+ }
92
+ /** Bounds of `live.wait`. */
93
+ export declare const MIN_LIVE_WAIT_MS = 5000;
94
+ export declare const MAX_LIVE_WAIT_MS: number;
95
+ /** The keys format 11 added (the `"camoufox"` engine also writes format 11). */
96
+ declare const FORMAT_11_KEYS: readonly ["userAgent", "proxy"];
97
+ /** The values of `engine`: `"chrome"` (the default), read mode, and Camoufox (format 11). */
98
+ declare const ENGINE_VALUES: readonly ["chrome", "lightpanda", "camoufox"];
99
+ /** What turno-browser records for an identity (`recorder.ts`, `recordings.ts`); all off by default. */
100
+ export interface RecordSettings {
101
+ /** Record every session's actions as a flow (`auto-<time>`), the newest few kept. */
102
+ flows?: boolean;
103
+ /** Playwright traces of each browser session, paused around vault sign-ins. */
104
+ traces?: boolean;
105
+ /** A screenshot after each action, skipped on a page that holds vault values. */
106
+ screenshots?: boolean;
107
+ /** Size cap of the identity's recordings, like `"200MB"`; the oldest go first. */
108
+ maxSize?: string;
109
+ }
110
+ /** How many agent sessions use the identity's browser at once (`sharing.ts`). */
111
+ type SharingSetting = "session" | "tabs";
40
112
  /** Where Chrome gets its cookie encryption key. */
41
113
  type KeychainMode = "mock" | "system";
42
114
  /** Resource types `block.types` may name: the heavy ones a page usually works without. */
@@ -89,13 +161,34 @@ export interface IdentitySettings {
89
161
  cache?: CacheSettings;
90
162
  /** `"system"`: Chrome encrypts cookies with the OS store's key; default `"mock"`. */
91
163
  keychain?: KeychainMode;
164
+ /** Human-like input: `level` (off, light, full, adaptive) and an optional `seed`. */
165
+ humanize?: HumanizeSettings;
166
+ /** `"tabs"`: several agent sessions at once, each in its own locked tabs; default `"session"`. */
167
+ sharing?: SharingSetting;
168
+ /** `"lightpanda"`: read mode on Lightpanda; `"camoufox"`: Camoufox; default `"chrome"`. */
169
+ engine?: (typeof ENGINE_VALUES)[number];
170
+ /** Connect to a Chrome the user has open: `"auto"`, a user data dir, or a loopback endpoint. */
171
+ attach?: string;
172
+ record?: RecordSettings;
173
+ /** Natural language actions (`browser_act`, `browser_extract`, `browser_observe`); off by default. */
174
+ act?: ActSettings;
175
+ /** A captcha solver for `browser_solve_captcha`; off by default. */
176
+ captcha?: CaptchaSettings;
177
+ /** With `"sharing": "tabs"`: how long a call waits for a held tab, and when an idle session lets go. */
178
+ tabLocks?: TabLockSettings;
179
+ /** The live view and take-over: `enabled` and `wait`; off by default. */
180
+ live?: LiveSettings;
181
+ /** `"coherent"`: the installed Chrome's own user agent and client hints, checked at launch. */
182
+ userAgent?: UserAgentMode;
183
+ /** A proxy for the identity's traffic; credentials only as `keychain:` references. */
184
+ proxy?: ProxySettings;
92
185
  /** ISO dates. */
93
186
  created: string;
94
187
  updated: string;
95
188
  }
96
189
  /** A change to identity.json: a value sets the key, `null` removes it. */
97
190
  export type SettingsPatch = {
98
- [K in "timezone" | "locale" | "languages" | "region" | "health" | (typeof FORMAT_2_KEYS)[number] | (typeof FORMAT_3_KEYS)[number]]?: IdentitySettings[K] | null;
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;
99
192
  };
100
193
  /**
101
194
  * The Chrome switches to drop for this identity's keychain setting, as Playwright launch
@@ -109,6 +202,15 @@ export declare function keychainArgs(settings: Pick<IdentitySettings, "keychain"
109
202
  * and the XDG folders follow the identity's environment instead of this process's.
110
203
  */
111
204
  export declare function chromeEnv(env: NodeJS.ProcessEnv): Record<string, string>;
205
+ /**
206
+ * Why an engine cannot record what `record` asks for. Attach mode: a trace covers every tab of
207
+ * the browser, the user's own too, so neither traces nor screenshots are taken there. Read mode:
208
+ * Lightpanda renders no page, so there is nothing to screenshot or screencast.
209
+ */
210
+ export declare function recordEngineClash(engine: string, record: {
211
+ traces?: unknown;
212
+ screenshots?: unknown;
213
+ }): string | undefined;
112
214
  export declare function identitySettingsPath(id: string, env?: NodeJS.ProcessEnv): string;
113
215
  /** The system's IANA time zone, as Chrome reports it when nothing overrides it. */
114
216
  export declare function systemTimezone(): string;
package/dist/settings.js CHANGED
@@ -1,7 +1,11 @@
1
1
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
2
2
  import { dirname, join } from "node:path";
3
3
  import { browserPaths as paths } from "turno-core/paths";
4
+ import { actProblems, captchaProblems } from "./opt-in-settings.js";
5
+ import { parseAttachTarget } from "./engine-attach.js";
4
6
  import { IdentityError, assertIdentityId } from "./ids.js";
7
+ import { HUMANIZE_LEVELS } from "./humanize.js";
8
+ import { networkEngineClash, networkProblems } from "./network.js";
5
9
  import { parseDuration, parseSize } from "./units.js";
6
10
  /**
7
11
  * identity.json: what stays fixed for one browser identity, so a site sees the same person in
@@ -27,6 +31,29 @@ import { parseDuration, parseSize } from "./units.js";
27
31
  * `"mock"` (the default, also when the key is missing) keeps Playwright's
28
32
  * `--use-mock-keychain` and `--password-store=basic`, a fixed public key; `"system"` drops
29
33
  * them, so Chrome uses the macOS Keychain or the Linux Secret Service.
34
+ * - `humanize` (format 4): human-like pointer, typing and scrolling (`humanize.ts`), off by default.
35
+ * - `sharing` (format 5): `"session"` (the default) serves one agent session at a time;
36
+ * `"tabs"` lets several sessions use the browser at once, each in its own locked tabs
37
+ * (`sharing.ts`; mcp.toml then runs the server with `exclusive = false`).
38
+ * - `engine`, `attach` (format 6): which engine runs the identity (`engine.ts`). `engine:
39
+ * "lightpanda"` is read mode; `attach` connects to a Chrome the user already has open
40
+ * (`"auto"`, a user data dir, or a loopback endpoint). Both off by default.
41
+ * - `record` (format 7): what turno-browser records for this identity, all off by default:
42
+ * `flows` (every session's actions as a flow, `recorder.ts`), `traces` (Playwright traces) and
43
+ * `screenshots` (one per action), the last two under the identity's state folder with a
44
+ * size cap (`maxSize`, default 200MB) and the oldest recordings removed first (`recordings.ts`).
45
+ * - `act`, `captcha` (format 8): natural language actions and captcha solving, both off by
46
+ * default and both sending page content to a model or a solver the user picks
47
+ * (`opt-in-settings.ts`). Keys are `keychain:` references, never values.
48
+ * - `tabLocks` (format 9): with `"sharing": "tabs"`, how long a call waits for a tab another
49
+ * session holds (`wait`, default 10s) and how long a session without calls keeps its tabs
50
+ * (`release`, default 5m) (`tab-locks.ts`). No effect with `"sharing": "session"`.
51
+ * - `live` (format 10): the live view and take-over (`live.ts`), off by default: `enabled` serves
52
+ * a view of the agent's tab on 127.0.0.1 and lets the user pause the agent; `wait` is how long
53
+ * a paused call waits for the user to resume before it fails (default 2m).
54
+ * - `userAgent`, `proxy` (format 11), and the `"camoufox"` value of `engine`: opt-in network and
55
+ * user agent settings (`network.ts`) and Camoufox as an alternate engine
56
+ * (`engine-camoufox.ts`), all off by default.
30
57
  *
31
58
  * A missing file means Chrome's own defaults, as before identity.json existed.
32
59
  */
@@ -37,11 +64,39 @@ import { parseDuration, parseSize } from "./units.js";
37
64
  * only when it uses one of them, so an older turno-browser keeps reading every other file and
38
65
  * refuses one it would misread with "update turno-browser".
39
66
  */
40
- export const IDENTITY_FORMAT_VERSION = 3;
67
+ export const IDENTITY_FORMAT_VERSION = 11;
41
68
  /** The keys format 2 added. */
42
69
  const FORMAT_2_KEYS = ["tabs", "backgroundThrottling", "settle", "block", "cache"];
43
70
  /** The keys format 3 added. */
44
71
  const FORMAT_3_KEYS = ["keychain"];
72
+ /** The keys format 4 added. */
73
+ const FORMAT_4_KEYS = ["humanize"];
74
+ /** The keys format 5 added. */
75
+ const FORMAT_5_KEYS = ["sharing"];
76
+ /** The keys format 6 added. */
77
+ const FORMAT_6_KEYS = ["engine", "attach"];
78
+ /** The keys format 7 added. */
79
+ const FORMAT_7_KEYS = ["record"];
80
+ /** The keys format 8 added. */
81
+ const FORMAT_8_KEYS = ["act", "captcha"];
82
+ /** The keys format 9 added. */
83
+ const FORMAT_9_KEYS = ["tabLocks"];
84
+ /** Longest `tabLocks.wait`: a call that waits longer for a tab is better off opening its own. */
85
+ const MAX_TAB_LOCK_WAIT_MS = 10 * 60_000;
86
+ /** Longest `tabLocks.release`. */
87
+ const MAX_TAB_LOCK_RELEASE_MS = 24 * 3_600_000;
88
+ /** The keys format 10 added. */
89
+ const FORMAT_10_KEYS = ["live"];
90
+ /** Bounds of `live.wait`. */
91
+ export const MIN_LIVE_WAIT_MS = 5_000;
92
+ export const MAX_LIVE_WAIT_MS = 30 * 60_000;
93
+ /** The keys format 11 added (the `"camoufox"` engine also writes format 11). */
94
+ const FORMAT_11_KEYS = ["userAgent", "proxy"];
95
+ /** The values of `engine`: `"chrome"` (the default), read mode, and Camoufox (format 11). */
96
+ const ENGINE_VALUES = ["chrome", "lightpanda", "camoufox"];
97
+ /** Recordings size cap bounds. */
98
+ const MIN_RECORD_BYTES = 10 * 1024 ** 2;
99
+ const MAX_RECORD_BYTES = 10 * 1024 ** 3;
45
100
  /** Playwright's switches that give Chrome a fixed key instead of the OS store's. */
46
101
  const MOCK_KEYCHAIN_SWITCHES = ["--use-mock-keychain", "--password-store=basic"];
47
102
  /** Resource types `block.types` may name: the heavy ones a page usually works without. */
@@ -59,6 +114,14 @@ const KEYS = new Set([
59
114
  "health",
60
115
  ...FORMAT_2_KEYS,
61
116
  ...FORMAT_3_KEYS,
117
+ ...FORMAT_4_KEYS,
118
+ ...FORMAT_5_KEYS,
119
+ ...FORMAT_6_KEYS,
120
+ ...FORMAT_7_KEYS,
121
+ ...FORMAT_8_KEYS,
122
+ ...FORMAT_9_KEYS,
123
+ ...FORMAT_10_KEYS,
124
+ ...FORMAT_11_KEYS,
62
125
  "created",
63
126
  "updated",
64
127
  ]);
@@ -133,6 +196,19 @@ function browserProblems(v, out) {
133
196
  }
134
197
  if (v.keychain !== undefined && v.keychain !== "mock" && v.keychain !== "system")
135
198
  out.push('keychain must be "mock" (the default) or "system"');
199
+ humanizeProblems(v.humanize, out);
200
+ if (v.sharing !== undefined && v.sharing !== "session" && v.sharing !== "tabs")
201
+ out.push('sharing must be "session" (the default, one agent session at a time) or "tabs"');
202
+ engineProblems(v, out);
203
+ recordProblems(v, out);
204
+ actProblems(v.act, out);
205
+ captchaProblems(v.captcha, v, out);
206
+ tabLockProblems(v.tabLocks, out);
207
+ liveProblems(v.live, out);
208
+ networkProblems(v, out);
209
+ const networkClash = networkEngineClash(engineOf(v), v);
210
+ if (networkClash)
211
+ out.push(networkClash);
136
212
  if (v.cache !== undefined) {
137
213
  const c = v.cache;
138
214
  if (!isObject(c))
@@ -147,6 +223,118 @@ function browserProblems(v, out) {
147
223
  }
148
224
  }
149
225
  }
226
+ function tabLockProblems(t, out) {
227
+ if (t === undefined)
228
+ return;
229
+ if (!isObject(t)) {
230
+ out.push('tabLocks must be an object, like { "wait": "30s", "release": "10m" }');
231
+ return;
232
+ }
233
+ const ms = (v) => (typeof v === "string" ? parseDuration(v) : undefined);
234
+ if (t.wait !== undefined) {
235
+ const wait = ms(t.wait);
236
+ if (wait === undefined || wait > MAX_TAB_LOCK_WAIT_MS)
237
+ out.push('tabLocks.wait must be a duration from "0" (fail at once) to "10m", like "30s"');
238
+ }
239
+ if (t.release !== undefined) {
240
+ const release = ms(t.release);
241
+ if (release === undefined || release > MAX_TAB_LOCK_RELEASE_MS)
242
+ out.push('tabLocks.release must be a duration from "0" (free between calls) to "24h", like "10m"');
243
+ }
244
+ unknownKeys(t, ["wait", "release"], "tabLocks", out);
245
+ }
246
+ function humanizeProblems(h, out) {
247
+ if (h === undefined)
248
+ return;
249
+ if (!isObject(h)) {
250
+ out.push('humanize must be an object, like { "level": "light" }');
251
+ return;
252
+ }
253
+ if (!HUMANIZE_LEVELS.includes(h.level))
254
+ out.push(`humanize.level must be ${HUMANIZE_LEVELS.map((l) => `"${l}"`).join(", ")}`);
255
+ if (h.seed !== undefined &&
256
+ (typeof h.seed !== "number" || !Number.isInteger(h.seed) || h.seed < 0 || h.seed >= 2 ** 32))
257
+ out.push("humanize.seed must be a whole number from 0 to 4294967295");
258
+ unknownKeys(h, ["level", "seed"], "humanize", out);
259
+ }
260
+ /** The engine identity.json asks for: attach wins, like at launch. */
261
+ function engineOf(v) {
262
+ return v.attach !== undefined ? "attach" : String(v.engine ?? "chrome");
263
+ }
264
+ /** Problems with the format 6 keys (and the format 11 `"camoufox"` engine). */
265
+ function engineProblems(v, out) {
266
+ if (v.engine !== undefined && !ENGINE_VALUES.includes(v.engine))
267
+ out.push('engine must be "chrome" (the default), "lightpanda" (read mode) or "camoufox"');
268
+ if (v.engine === "camoufox" && v.keychain === "system")
269
+ out.push('keychain does not go with engine "camoufox": it sets how Chrome encrypts its cookies');
270
+ if (v.attach !== undefined) {
271
+ const target = typeof v.attach === "string" ? parseAttachTarget(v.attach) : { error: "attach must be a string" };
272
+ if ("error" in target)
273
+ out.push(target.error);
274
+ else if (v.engine === "lightpanda" || v.engine === "camoufox")
275
+ out.push(`attach does not go with engine "${v.engine}": pick one`);
276
+ else if (v.sharing === "tabs")
277
+ out.push('attach does not go with sharing "tabs": pick one');
278
+ }
279
+ const level = isObject(v.humanize) ? v.humanize.level : undefined;
280
+ if (v.engine === "lightpanda" && level !== undefined && level !== "off")
281
+ out.push('humanize does not go with engine "lightpanda": read mode lays out no page to move a pointer over');
282
+ }
283
+ /** Problems with the format 7 `record` key, alone and with the engine keys. */
284
+ function recordProblems(v, out) {
285
+ if (v.record === undefined)
286
+ return;
287
+ const r = v.record;
288
+ if (!isObject(r)) {
289
+ out.push("record must be an object with flows, traces, screenshots or maxSize");
290
+ return;
291
+ }
292
+ for (const k of ["flows", "traces", "screenshots"])
293
+ if (r[k] !== undefined && typeof r[k] !== "boolean")
294
+ out.push(`record.${k} must be true or false`);
295
+ if (r.maxSize !== undefined) {
296
+ const bytes = typeof r.maxSize === "string" ? parseSize(r.maxSize) : undefined;
297
+ if (bytes === undefined || bytes < MIN_RECORD_BYTES || bytes > MAX_RECORD_BYTES)
298
+ out.push('record.maxSize must be a size from "10MB" to "10GB", like "200MB"');
299
+ }
300
+ unknownKeys(r, ["flows", "traces", "screenshots", "maxSize"], "record", out);
301
+ const clash = recordEngineClash(engineOf(v), r);
302
+ if (clash)
303
+ out.push(clash);
304
+ }
305
+ /** Problems with the format 8 `live` key. */
306
+ function liveProblems(l, out) {
307
+ if (l === undefined)
308
+ return;
309
+ if (!isObject(l)) {
310
+ out.push('live must be an object, like { "enabled": true }');
311
+ return;
312
+ }
313
+ if (l.enabled !== undefined && typeof l.enabled !== "boolean")
314
+ out.push("live.enabled must be true or false");
315
+ if (l.wait !== undefined) {
316
+ const ms = typeof l.wait === "string" ? parseDuration(l.wait) : undefined;
317
+ if (ms === undefined || ms < MIN_LIVE_WAIT_MS || ms > MAX_LIVE_WAIT_MS)
318
+ out.push('live.wait must be a duration from "5s" to "30m", like "2m"');
319
+ }
320
+ unknownKeys(l, ["enabled", "wait"], "live", out);
321
+ }
322
+ /**
323
+ * Why an engine cannot record what `record` asks for. Attach mode: a trace covers every tab of
324
+ * the browser, the user's own too, so neither traces nor screenshots are taken there. Read mode:
325
+ * Lightpanda renders no page, so there is nothing to screenshot or screencast.
326
+ */
327
+ export function recordEngineClash(engine, record) {
328
+ const asked = [record.traces === true && "traces", record.screenshots === true && "screenshots"].filter(Boolean);
329
+ if (!asked.length)
330
+ return undefined;
331
+ const what = `record.${asked.join(" and record.")}`;
332
+ if (engine === "attach")
333
+ return `${what} do not go with attach mode: a trace or screenshot could show your own tabs. Keep record.flows only, or drop attach`;
334
+ if (engine === "lightpanda")
335
+ return `${what} do not go with engine "lightpanda": read mode renders no page to screenshot or trace. Keep record.flows only, or use engine "chrome"`;
336
+ return undefined;
337
+ }
150
338
  export function identitySettingsPath(id, env = process.env) {
151
339
  assertIdentityId(id);
152
340
  return join(paths(env).identitiesDir, `${id}.json`);
@@ -280,11 +468,21 @@ export function writeIdentitySettings(id, patch, env = process.env, now = new Da
280
468
  else
281
469
  next[key] = value;
282
470
  }
283
- next.version = FORMAT_3_KEYS.some((k) => next[k] !== undefined)
284
- ? 3
285
- : FORMAT_2_KEYS.some((k) => next[k] !== undefined)
286
- ? 2
287
- : 1;
471
+ const formats = [
472
+ FORMAT_11_KEYS,
473
+ FORMAT_10_KEYS,
474
+ FORMAT_9_KEYS,
475
+ FORMAT_8_KEYS,
476
+ FORMAT_7_KEYS,
477
+ FORMAT_6_KEYS,
478
+ FORMAT_5_KEYS,
479
+ FORMAT_4_KEYS,
480
+ FORMAT_3_KEYS,
481
+ FORMAT_2_KEYS,
482
+ ];
483
+ // 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));
485
+ next.version = newest < 0 ? 1 : IDENTITY_FORMAT_VERSION - newest;
288
486
  if (typeof next.locale === "string")
289
487
  next.locale = canonicalLocale(next.locale) ?? next.locale;
290
488
  if (Array.isArray(next.languages))
@@ -0,0 +1,96 @@
1
+ import type { BrowserContext, Page } from "patchright-core";
2
+ import type { TabView } from "./governor.js";
3
+ import { type TabLockPolicy, TabLocks } from "./tab-locks.js";
4
+ import { type BrowserBackendInstance, type McpConfig, type ToolResult } from "./upstream.js";
5
+ /**
6
+ * `"sharing": "tabs"`: several agent sessions work in one identity's browser at once, each in
7
+ * its own tabs. mcpd relays every session's calls over the one stdio connection of a shared,
8
+ * non-exclusive server and tells them apart by `_meta["io.turno/session"]`.
9
+ *
10
+ * Why one upstream `BrowserBackend` per session: upstream keeps the current tab, the tab list,
11
+ * the modal states and the snapshot refs in the backend's `Context`, and each tool reads the
12
+ * current tab more than once while it runs (the action, then the snapshot of the result). One
13
+ * backend for every session would mean either a single current tab, so two sessions' calls
14
+ * would have to run one after the other, or a current tab swapped under a call in flight.
15
+ * Several backends on one browser context work (verified with patchright-core 1.64.3 and a
16
+ * real Chrome, `test/tab-sharing.test.ts`): each `Context` lists every page of the context,
17
+ * keeps its own current tab, and two sessions' navigations run at the same time on their own
18
+ * tabs; disposing one leaves the pages and the browser alone. What turno adds:
19
+ *
20
+ * - The first backend (the one that launched the browser) stays the root: it owns the browser's
21
+ * lifetime, the idle limit and upstream's routes and init scripts. The others get a config
22
+ * without `initScript`, `initPage` and the network origins, so a page is not set up once per
23
+ * session, and their disposal closes nothing.
24
+ * - Upstream points a backend that has no current tab at whatever page opens next, and at a
25
+ * neighbour when its tab closes. Before every call turno points the session's backend at the
26
+ * session's own tab (the one it last worked on, else the one it last used, else a free current
27
+ * tab, else a new one), and locks it (`tab-locks.ts`).
28
+ * - `browser_close` closes only the session's tabs: the browser stays for the others.
29
+ */
30
+ export type SharingMode = "session" | "tabs";
31
+ /** One session's backend and the config copy it reads on every call. */
32
+ export interface SessionView {
33
+ backend: BrowserBackendInstance;
34
+ config: McpConfig;
35
+ }
36
+ export interface TabSharingOptions {
37
+ context: BrowserContext;
38
+ /** The backend that launched the browser: it serves calls without a session id. */
39
+ root: SessionView;
40
+ /** A new backend on the same browser context (config from `viewConfig`). */
41
+ createView(): Promise<SessionView>;
42
+ policy: TabLockPolicy;
43
+ now?: () => number;
44
+ }
45
+ /**
46
+ * The config of a session's backend: the root's, without what upstream installs on the browser
47
+ * context for each backend (init scripts, the init page module, the allowed and blocked origin
48
+ * routes). The root installed them already and keeps them for the life of the browser.
49
+ */
50
+ export declare function viewConfig(config: McpConfig): McpConfig;
51
+ export declare class TabSharing {
52
+ private readonly options;
53
+ readonly locks: TabLocks<Page>;
54
+ private readonly views;
55
+ private readonly ready;
56
+ /** The tab each session last worked on. */
57
+ private readonly working;
58
+ private readonly watched;
59
+ private disposed;
60
+ constructor(options: TabSharingOptions);
61
+ /** The backend of `session`, created on its first call (`DIRECT_SESSION`: the root). */
62
+ view(session: string): Promise<SessionView>;
63
+ /** The tabs as one session's backend sees them, for the tab governor. */
64
+ tabView(view: SessionView): TabView;
65
+ /** Who holds a page, for the tab governor's cap. */
66
+ owner(page: Page): string | undefined;
67
+ /** Every page a session works on now: the governor never parks or closes them. */
68
+ protectedPages(): Page[];
69
+ /** A page Chrome opened: a popup belongs to the session that holds its opener. */
70
+ adopt(page: Page): Promise<void>;
71
+ /**
72
+ * Before a stock call of `session`: points its backend at its own tab and locks the tab the call
73
+ * acts on. Returns the error for the call when another session holds that tab past the wait.
74
+ */
75
+ before(session: string, name: string, args: Record<string, unknown>, view: SessionView, signal?: AbortSignal): Promise<string | undefined>;
76
+ /** After a call of `session`: the tab its backend now points at is its own. */
77
+ after(session: string, view: SessionView): void;
78
+ /** `browser_close` of one session: closes its tabs and lets go of them; the browser stays. */
79
+ close(session: string): Promise<ToolResult>;
80
+ /** mcpd said the session ended: its tabs are free (they stay open; the tab governor parks and closes them). */
81
+ endSession(session: string): Promise<void>;
82
+ /** Marks, in a tab list of a result, the tabs other sessions hold. */
83
+ annotate(text: string, session: string, view: SessionView): string;
84
+ /** The browser closed: every session's backend goes (the root is the host's). */
85
+ dispose(): void;
86
+ /** The tab `session` should act on, or undefined when it needs a new one. */
87
+ private pick;
88
+ /** Points the backend at `page` without bringing it to the front. */
89
+ private select;
90
+ private lock;
91
+ private claim;
92
+ private watch;
93
+ /** Backends of sessions that lapsed (no call for `releaseMs`) go; a new call makes a new one. */
94
+ private prune;
95
+ private dropView;
96
+ }