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
package/dist/live.d.ts ADDED
@@ -0,0 +1,120 @@
1
+ import type { LiveSettings } from "./settings.js";
2
+ /**
3
+ * The live view and take-over, the part that needs no browser: the policy (identity.json `live`
4
+ * and the server flags), the pause gate that holds the agent's calls while the user acts, and
5
+ * the note that tells the agent what changed. The HTTP side and the screencast are in
6
+ * `live-server.ts`; the host wires both into every call (`host.ts`).
7
+ *
8
+ * How a pause works:
9
+ *
10
+ * - The user pauses (the live view's Pause button, or `turno browser pause <id>`). A call that is
11
+ * running finishes; the next call of any session waits, up to `live.wait` (2 minutes by
12
+ * default), for the user to resume. A batch or replay in progress stops at its next step.
13
+ * - On resume the held call gets a note first: how long the pause lasted and what changed in the
14
+ * browser's tabs (the current tab's URL and title, tabs opened and closed, input from the live
15
+ * view). When nothing changed, the call runs. When something changed, a call that only reads
16
+ * (a snapshot, the tab list) runs; any other call does not, because the refs of the agent's last
17
+ * snapshot may now point elsewhere, and a fresh snapshot comes back instead.
18
+ * - When the wait runs out the call fails with a message that says the user still has the
19
+ * browser; the next call waits again.
20
+ */
21
+ /** How long a paused call waits for the user when identity.json and the flags say nothing. */
22
+ export declare const DEFAULT_LIVE_WAIT_MS: number;
23
+ /** `turno-browser-mcp --live` and `--live-wait`: each wins over identity.json `live`. */
24
+ export interface LiveFlags {
25
+ live?: boolean;
26
+ waitMs?: number;
27
+ }
28
+ export interface LivePolicy {
29
+ enabled: boolean;
30
+ waitMs: number;
31
+ }
32
+ /** The live policy of a server: flags, then identity.json, then off. */
33
+ export declare function resolveLive(settings: LiveSettings | undefined, flags?: LiveFlags): LivePolicy;
34
+ /**
35
+ * Where a running server says how to reach its live view: its pid, the control socket and the
36
+ * port, never a token (`live-server.ts` writes it, `live-client.ts` reads it).
37
+ */
38
+ export declare function liveFilePath(id: string, env?: NodeJS.ProcessEnv): string;
39
+ export interface LiveFile {
40
+ version: 1;
41
+ pid: number;
42
+ socket: string;
43
+ port: number;
44
+ started: string;
45
+ }
46
+ /**
47
+ * Why the live view shows no pixels with this engine (read mode, attach mode, Camoufox);
48
+ * undefined when it can. Pause and resume
49
+ * work with every engine.
50
+ */
51
+ export declare function viewRefusal(engine: string | undefined): string | undefined;
52
+ /** One tab as the note compares it before and after a pause. */
53
+ export interface TabState {
54
+ id: number;
55
+ url: string;
56
+ title: string;
57
+ }
58
+ /** What a held call learns when the gate lets it go. */
59
+ export type GateOutcome = {
60
+ kind: "open";
61
+ } | {
62
+ kind: "resumed";
63
+ pausedMs: number;
64
+ by: string;
65
+ /** The tabs when the pause started (empty when no browser ran). */
66
+ before: TabState[];
67
+ /** Clicks, keys and scrolls the user sent through the live view during the pause. */
68
+ inputs: number;
69
+ } | {
70
+ kind: "timeout";
71
+ pausedMs: number;
72
+ by: string;
73
+ } | {
74
+ kind: "aborted";
75
+ };
76
+ /** Holds calls while the user has the browser. One per server: a pause holds every session. */
77
+ export declare class PauseGate {
78
+ private readonly now;
79
+ private pause;
80
+ private waiting;
81
+ constructor(now?: () => number);
82
+ get paused(): {
83
+ since: number;
84
+ by: string;
85
+ } | undefined;
86
+ /** Calls waiting for the user now. */
87
+ get held(): number;
88
+ /** Starts a pause; false when one is already on. `before` is the tabs as the agent left them. */
89
+ start(by: string, before?: Promise<TabState[]>): boolean;
90
+ /** Ends the pause and lets every held call go; false when there was none. */
91
+ resume(): boolean;
92
+ /** The user clicked, typed or scrolled through the live view. */
93
+ noteInput(): void;
94
+ /** Waits while paused, at most `waitMs`; resolves at once when there is no pause. */
95
+ wait(waitMs: number, signal?: AbortSignal): Promise<GateOutcome>;
96
+ }
97
+ /** `65000` as "1m 05s", `9000` as "9s". */
98
+ export declare function formatPause(ms: number): string;
99
+ /**
100
+ * What changed in the tabs between the pause and now, one line each, from the point of view
101
+ * of the session whose current tab was `currentBefore` and is `currentAfter` now.
102
+ */
103
+ export declare function describeChanges(before: readonly TabState[], after: readonly TabState[], currentBefore: number | undefined, currentAfter: number | undefined, inputs: number): {
104
+ changed: boolean;
105
+ lines: string[];
106
+ };
107
+ /** The section a held call's result starts with. */
108
+ export declare function resumeNote(o: {
109
+ pausedMs: number;
110
+ by: string;
111
+ lines: readonly string[];
112
+ tool: string;
113
+ ran: boolean;
114
+ /** A flow is being recorded: what the user did is not in it. */
115
+ recordingFlow?: boolean;
116
+ /** The browser is not running, so there is no snapshot. */
117
+ noBrowser?: boolean;
118
+ }): string;
119
+ /** The error of a call whose wait ran out. */
120
+ export declare function timeoutMessage(identity: string, tool: string, pausedMs: number, by: string, waitMs: number): string;
package/dist/live.js ADDED
@@ -0,0 +1,203 @@
1
+ import { join } from "node:path";
2
+ import { identityStateDir } from "./ids.js";
3
+ import { parseDuration } from "./units.js";
4
+ /**
5
+ * The live view and take-over, the part that needs no browser: the policy (identity.json `live`
6
+ * and the server flags), the pause gate that holds the agent's calls while the user acts, and
7
+ * the note that tells the agent what changed. The HTTP side and the screencast are in
8
+ * `live-server.ts`; the host wires both into every call (`host.ts`).
9
+ *
10
+ * How a pause works:
11
+ *
12
+ * - The user pauses (the live view's Pause button, or `turno browser pause <id>`). A call that is
13
+ * running finishes; the next call of any session waits, up to `live.wait` (2 minutes by
14
+ * default), for the user to resume. A batch or replay in progress stops at its next step.
15
+ * - On resume the held call gets a note first: how long the pause lasted and what changed in the
16
+ * browser's tabs (the current tab's URL and title, tabs opened and closed, input from the live
17
+ * view). When nothing changed, the call runs. When something changed, a call that only reads
18
+ * (a snapshot, the tab list) runs; any other call does not, because the refs of the agent's last
19
+ * snapshot may now point elsewhere, and a fresh snapshot comes back instead.
20
+ * - When the wait runs out the call fails with a message that says the user still has the
21
+ * browser; the next call waits again.
22
+ */
23
+ /** How long a paused call waits for the user when identity.json and the flags say nothing. */
24
+ export const DEFAULT_LIVE_WAIT_MS = 2 * 60_000;
25
+ /** The live policy of a server: flags, then identity.json, then off. */
26
+ export function resolveLive(settings, flags = {}) {
27
+ const wait = settings?.wait === undefined ? undefined : parseDuration(settings.wait);
28
+ return {
29
+ enabled: flags.live ?? settings?.enabled ?? false,
30
+ waitMs: flags.waitMs ?? wait ?? DEFAULT_LIVE_WAIT_MS,
31
+ };
32
+ }
33
+ /**
34
+ * Where a running server says how to reach its live view: its pid, the control socket and the
35
+ * port, never a token (`live-server.ts` writes it, `live-client.ts` reads it).
36
+ */
37
+ export function liveFilePath(id, env = process.env) {
38
+ return join(identityStateDir(id, env), "live.json");
39
+ }
40
+ /**
41
+ * Why the live view shows no pixels with this engine (read mode, attach mode, Camoufox);
42
+ * undefined when it can. Pause and resume
43
+ * work with every engine.
44
+ */
45
+ export function viewRefusal(engine) {
46
+ if (engine === "lightpanda")
47
+ return "Read mode (Lightpanda) renders no pixels, so there is nothing to show. Pause and resume still work.";
48
+ if (engine === "attach")
49
+ return "Attach mode drives your own Chrome, which you already see; a view would stream your own tabs, so it is off. Pause and resume still work.";
50
+ if (engine === "camoufox")
51
+ return "The view is a Chrome DevTools Protocol screencast, and Camoufox is a Firefox build that has none, so there is nothing to show; Camoufox's own window shows the page when it runs headed. Pause and resume still work.";
52
+ return undefined;
53
+ }
54
+ /** Holds calls while the user has the browser. One per server: a pause holds every session. */
55
+ export class PauseGate {
56
+ now;
57
+ pause;
58
+ waiting = 0;
59
+ constructor(now = Date.now) {
60
+ this.now = now;
61
+ }
62
+ get paused() {
63
+ return this.pause && { since: this.pause.since, by: this.pause.by };
64
+ }
65
+ /** Calls waiting for the user now. */
66
+ get held() {
67
+ return this.waiting;
68
+ }
69
+ /** Starts a pause; false when one is already on. `before` is the tabs as the agent left them. */
70
+ start(by, before = Promise.resolve([])) {
71
+ if (this.pause)
72
+ return false;
73
+ let release;
74
+ const done = new Promise((r) => {
75
+ release = r;
76
+ });
77
+ before.catch(() => { });
78
+ this.pause = { since: this.now(), by, before, inputs: 0, done, release };
79
+ return true;
80
+ }
81
+ /** Ends the pause and lets every held call go; false when there was none. */
82
+ resume() {
83
+ const p = this.pause;
84
+ if (!p)
85
+ return false;
86
+ this.pause = undefined;
87
+ p.release();
88
+ return true;
89
+ }
90
+ /** The user clicked, typed or scrolled through the live view. */
91
+ noteInput() {
92
+ if (this.pause)
93
+ this.pause.inputs++;
94
+ }
95
+ /** Waits while paused, at most `waitMs`; resolves at once when there is no pause. */
96
+ async wait(waitMs, signal) {
97
+ const p = this.pause;
98
+ if (!p)
99
+ return { kind: "open" };
100
+ if (signal?.aborted)
101
+ return { kind: "aborted" };
102
+ this.waiting++;
103
+ let timer;
104
+ let onAbort;
105
+ try {
106
+ const outcome = await Promise.race([
107
+ p.done.then(() => "resumed"),
108
+ new Promise((r) => {
109
+ // Each call waits the whole time: a call that arrives late in a pause is held as long.
110
+ timer = setTimeout(() => r("timeout"), waitMs);
111
+ }),
112
+ new Promise((r) => {
113
+ onAbort = () => r("aborted");
114
+ signal?.addEventListener("abort", onAbort, { once: true });
115
+ }),
116
+ ]);
117
+ if (outcome === "aborted")
118
+ return { kind: "aborted" };
119
+ const pausedMs = this.now() - p.since;
120
+ if (outcome === "timeout")
121
+ return { kind: "timeout", pausedMs, by: p.by };
122
+ return { kind: "resumed", pausedMs, by: p.by, before: await p.before.catch(() => []), inputs: p.inputs };
123
+ }
124
+ finally {
125
+ this.waiting--;
126
+ if (timer)
127
+ clearTimeout(timer);
128
+ if (onAbort)
129
+ signal?.removeEventListener("abort", onAbort);
130
+ }
131
+ }
132
+ }
133
+ /** `65000` as "1m 05s", `9000` as "9s". */
134
+ export function formatPause(ms) {
135
+ const s = Math.max(0, Math.round(ms / 1000));
136
+ if (s < 60)
137
+ return `${s}s`;
138
+ const m = Math.floor(s / 60);
139
+ return `${m}m ${String(s % 60).padStart(2, "0")}s`;
140
+ }
141
+ /**
142
+ * What changed in the tabs between the pause and now, one line each, from the point of view
143
+ * of the session whose current tab was `currentBefore` and is `currentAfter` now.
144
+ */
145
+ export function describeChanges(before, after, currentBefore, currentAfter, inputs) {
146
+ const lines = [];
147
+ const was = new Map(before.map((t) => [t.id, t]));
148
+ const now = new Map(after.map((t) => [t.id, t]));
149
+ const cb = currentBefore === undefined ? undefined : was.get(currentBefore);
150
+ const ca = currentAfter === undefined ? undefined : now.get(currentAfter);
151
+ if (cb && ca && cb.id === ca.id) {
152
+ if (cb.url !== ca.url)
153
+ lines.push(`Current tab: ${cb.url} -> ${ca.url}`);
154
+ if (cb.title !== ca.title)
155
+ lines.push(`Title: ${JSON.stringify(cb.title)} -> ${JSON.stringify(ca.title)}`);
156
+ }
157
+ else if (ca && currentBefore !== undefined) {
158
+ lines.push(`Current tab is now another tab: ${ca.url} (${JSON.stringify(ca.title)})`);
159
+ }
160
+ for (const t of after)
161
+ if (!was.has(t.id))
162
+ lines.push(`New tab: ${t.url}`);
163
+ for (const t of before)
164
+ if (!now.has(t.id))
165
+ lines.push(`Closed tab: ${t.url}`);
166
+ for (const t of after) {
167
+ const old = was.get(t.id);
168
+ if (!old || t.id === ca?.id || t.id === cb?.id)
169
+ continue;
170
+ if (old.url !== t.url)
171
+ lines.push(`Another tab: ${old.url} -> ${t.url}`);
172
+ }
173
+ if (inputs > 0)
174
+ lines.push(`The user clicked, typed or scrolled ${inputs} time${inputs === 1 ? "" : "s"} through the live view.`);
175
+ return { changed: lines.length > 0, lines };
176
+ }
177
+ /** The section a held call's result starts with. */
178
+ export function resumeNote(o) {
179
+ const out = [
180
+ "### Paused by the user",
181
+ `The user paused this browser (${o.by}) for ${formatPause(o.pausedMs)} and has resumed it.`,
182
+ ];
183
+ if (o.lines.length)
184
+ out.push("While you waited:", ...o.lines.map((l) => `- ${l}`));
185
+ else
186
+ out.push("Nothing changed in the browser's tabs (same tabs, URLs and titles).");
187
+ if (o.ran)
188
+ out.push(`Your ${o.tool} call ran after the resume; its result follows.`);
189
+ else if (o.noBrowser)
190
+ out.push(`Your ${o.tool} call was not run. The browser is not running now; start again from a navigation.`);
191
+ else
192
+ out.push(`Your ${o.tool} call was not run: the browser changed while you waited, so the refs of your last snapshot may point elsewhere. A fresh snapshot follows; decide the next step from it.`);
193
+ if (o.recordingFlow)
194
+ out.push("The flow you are recording does not have what the user did.");
195
+ return out.join("\n");
196
+ }
197
+ /** The error of a call whose wait ran out. */
198
+ export function timeoutMessage(identity, tool, pausedMs, by, waitMs) {
199
+ return (`The user paused browser identity "${identity}" ${formatPause(pausedMs)} ago (${by}) and has not resumed it ` +
200
+ `within ${formatPause(waitMs)}, so ${tool} was not run. The user is probably acting in the browser: wait, or ask ` +
201
+ `them to resume (Resume in the live view, or turno browser resume ${identity}), then call again.`);
202
+ }
203
+ //# sourceMappingURL=live.js.map
@@ -1,5 +1,7 @@
1
+ import type { Page } from "patchright-core";
1
2
  import type { SecretStore } from "turno-core/secrets";
2
3
  import type { IdentityRef } from "./engine.js";
4
+ import type { HumanInput } from "./human-input.js";
3
5
  import type { Redactor, VaultGuard } from "./redact.js";
4
6
  import type { TurnoTool } from "./tools.js";
5
7
  /**
@@ -25,6 +27,17 @@ export interface VaultAccess {
25
27
  guard: VaultGuard;
26
28
  /** The secret store (tests inject a fake); default: this machine's. */
27
29
  store?: SecretStore;
30
+ /**
31
+ * Runs before a value goes into the page: a recording saves its trace and holds the page,
32
+ * so the fill is never traced or screenshotted (`recordings.ts`).
33
+ */
34
+ beforeFill?: (page: Page) => Promise<void>;
35
+ /**
36
+ * Human-like input, when the identity's humanize is on: each value is typed key by key into
37
+ * its field, as `browser_type` would. Keys go to Chrome's input pipeline and nowhere else:
38
+ * not into a result (the redactor), a trace (`beforeFill` stopped it) or a log.
39
+ */
40
+ input?: HumanInput;
28
41
  }
29
42
  /** The tool. Its schema is built on first use, so importing the registry does not load the bundle. */
30
43
  export declare function loginTool(): TurnoTool;
@@ -156,6 +156,7 @@ export function loginTool() {
156
156
  code = totp(credential.totp);
157
157
  }
158
158
  }
159
+ await vault.beforeFill?.(page);
159
160
  // Redact first: from here on no result or error of this server shows a value.
160
161
  vault.redactor.add(credential.username, `${siteKey} username`);
161
162
  vault.redactor.add(credential.password, `${siteKey} password`);
@@ -169,7 +170,10 @@ export function loginTool() {
169
170
  };
170
171
  const filled = [];
171
172
  let last;
172
- for (const [field, locator] of fields) {
173
+ // With humanize on, the fields are clicked into and typed key by key (`human-input.ts`).
174
+ const humanized = vault.input && vault.input.levelFor(page) !== "off" ? vault.input : undefined;
175
+ for (const [field, found] of fields) {
176
+ const locator = humanized ? humanized.wrapLocator(found, page) : found;
173
177
  try {
174
178
  await locator.fill(values[field], { timeout: 5_000 });
175
179
  }
package/dist/login.d.ts CHANGED
@@ -4,10 +4,13 @@ export interface LoginOptions {
4
4
  url?: string;
5
5
  }
6
6
  /**
7
- * Opens the identity's persistent Chrome headed, with the same stealth settings as the MCP
7
+ * Opens the identity's persistent Chrome headed, with the same launch settings as the MCP
8
8
  * server (Chrome channel, no fixed viewport, the identity's languages and time zone), and
9
9
  * resolves when the user closes the last window or quits Chrome. Used once per site so the user
10
10
  * signs in by hand. It holds the identity's runtime lock while the window is open, and clears
11
11
  * the last session health result, so the next launch checks the sign-in again.
12
+ *
13
+ * With identity.json `proxy`, the sign-in goes through the same proxy as the agent's sessions,
14
+ * so the site sees one network for both. A Camoufox identity is refused: it keeps its own profile.
12
15
  */
13
16
  export declare function loginIdentity(id: string, options?: LoginOptions): Promise<void>;
package/dist/login.js CHANGED
@@ -2,14 +2,18 @@ import { mkdirSync } from "node:fs";
2
2
  import { clearHealth } from "./health.js";
3
3
  import { IdentityError, identityDir, inUseBy, isInUse } from "./identities.js";
4
4
  import { readLockPid } from "./lifecycle.js";
5
+ import { CHROME_PROXY_ARGS, resolveProxy } from "./network.js";
5
6
  import { acquireRuntimeLock } from "./runtime-lock.js";
6
7
  import { chromeEnv, keychainArgs, launchSettings, readIdentitySettings, systemTimezone } from "./settings.js";
7
8
  /**
8
- * Opens the identity's persistent Chrome headed, with the same stealth settings as the MCP
9
+ * Opens the identity's persistent Chrome headed, with the same launch settings as the MCP
9
10
  * server (Chrome channel, no fixed viewport, the identity's languages and time zone), and
10
11
  * resolves when the user closes the last window or quits Chrome. Used once per site so the user
11
12
  * signs in by hand. It holds the identity's runtime lock while the window is open, and clears
12
13
  * the last session health result, so the next launch checks the sign-in again.
14
+ *
15
+ * With identity.json `proxy`, the sign-in goes through the same proxy as the agent's sessions,
16
+ * so the site sees one network for both. A Camoufox identity is refused: it keeps its own profile.
13
17
  */
14
18
  export async function loginIdentity(id, options = {}) {
15
19
  const env = options.env ?? process.env;
@@ -20,6 +24,10 @@ export async function loginIdentity(id, options = {}) {
20
24
  if (isInUse(id, env))
21
25
  throw new IdentityError(`identity "${id}" is in use (an MCP session holds its Chrome); close it first`);
22
26
  const settings = readIdentitySettings(id, env);
27
+ if (settings?.engine === "camoufox" && settings.attach === undefined)
28
+ throw new IdentityError(`identity "${id}" runs on Camoufox, which keeps its own profile, and \`turno browser login\` opens the Chrome profile: sign in from an agent session (browser_login with the vault), or use --engine chrome`);
29
+ // Read before the lock, so a missing secret leaves nothing to undo; the value goes only to Chrome.
30
+ const proxy = settings?.proxy ? await resolveProxy(settings.proxy, env, () => { }) : undefined;
23
31
  const held = acquireRuntimeLock(id, env, { holder: "login" });
24
32
  try {
25
33
  mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -29,7 +37,8 @@ export async function loginIdentity(id, options = {}) {
29
37
  channel: "chrome",
30
38
  headless: false,
31
39
  viewport: null,
32
- ...(applied.args.length ? { args: applied.args } : {}),
40
+ ...(applied.args.length || proxy ? { args: [...applied.args, ...(proxy ? CHROME_PROXY_ARGS : [])] } : {}),
41
+ ...(proxy ? { proxy } : {}),
33
42
  ...(applied.timezoneId ? { timezoneId: applied.timezoneId } : {}),
34
43
  ...keychainArgs(settings),
35
44
  // Chrome gets the caller's environment (HOME, XDG dirs), not this process's.
@@ -0,0 +1,74 @@
1
+ import type { BrowserContext, Page } from "patchright-core";
2
+ import { type ExpectedIdentity, type ResolvedProxy } from "./network.js";
3
+ import { type IdentitySettings } from "./settings.js";
4
+ import type { McpConfig } from "./upstream.js";
5
+ /**
6
+ * How the chrome engine applies identity.json `proxy` and `userAgent` (`network.ts`). Both are
7
+ * settled before Chrome starts: a missing secret or an unknown Chrome version stops the launch
8
+ * with nothing to undo.
9
+ *
10
+ * `userAgent: "coherent"` changes nothing in a headed Chrome, which already presents itself
11
+ * as it is; the launch check still runs. A headless Chrome says HeadlessChrome, so it gets two
12
+ * things, measured with Chrome 157:
13
+ *
14
+ * - the `--user-agent` switch with the headed string for the same version and OS, which every
15
+ * request, popup and worker carries from the start; on its own it blanks the client hints'
16
+ * high entropy values (full version list, architecture, platform version), which a real
17
+ * Chrome never does;
18
+ * - so each page also gets those values back through `Emulation.setUserAgentOverride`, with
19
+ * the metadata this same Chrome reports when nothing overrides it, read once per Chrome
20
+ * version by a short headless launch on a throwaway profile and kept in the state folder.
21
+ * Dedicated workers take them from their page.
22
+ *
23
+ * A tab a tool opens gets them before its first navigation. A popup a page opens gets them as
24
+ * soon as it exists, which can be after its first document loaded: that document reads blank
25
+ * high entropy values (the user agent string is right there too).
26
+ */
27
+ export interface ChromeNetwork {
28
+ /** Chrome switches to add. */
29
+ args: string[];
30
+ /** Playwright's `proxy` launch option, credentials included. */
31
+ proxy?: ResolvedProxy;
32
+ /** With `userAgent`, what the launch check expects the page to read. */
33
+ verify?: ExpectedIdentity;
34
+ /** With `userAgent` in a headless Chrome: the string and metadata each page gets. */
35
+ pin?: UserAgentPin;
36
+ }
37
+ /** The client hints metadata of `Emulation.setUserAgentOverride`, as this Chrome reports it. */
38
+ interface UserAgentMetadata {
39
+ brands: {
40
+ brand: string;
41
+ version: string;
42
+ }[];
43
+ fullVersionList: {
44
+ brand: string;
45
+ version: string;
46
+ }[];
47
+ platform: string;
48
+ platformVersion: string;
49
+ architecture: string;
50
+ model: string;
51
+ mobile: boolean;
52
+ bitness: string;
53
+ wow64: boolean;
54
+ }
55
+ export interface UserAgentPin {
56
+ userAgent: string;
57
+ metadata: UserAgentMetadata;
58
+ }
59
+ export declare function chromeNetwork(settings: IdentitySettings, config: McpConfig, env: NodeJS.ProcessEnv, secret: (value: string, label: string) => void): Promise<ChromeNetwork>;
60
+ /** Gives every page of the context the pinned user agent and metadata; `ready` resolves once a page has them. */
61
+ export declare function pinUserAgent(context: BrowserContext, pin: UserAgentPin): {
62
+ ready(page: Page): Promise<void>;
63
+ };
64
+ /**
65
+ * The launch check of `userAgent: "coherent"`: loads a blank page of its own on an https origin
66
+ * (client hints exist only in a secure context), answered by a route so no request leaves the
67
+ * machine, reads what the page sees and what the request carried, and refuses the browser when
68
+ * anything contradicts the rest, or the user agent names another version than the Chrome that
69
+ * runs. A headed Chrome shows that tab for a moment. The caller closes the browser on a throw.
70
+ */
71
+ export declare function verifyCoherence(context: BrowserContext, version: string, expected: ExpectedIdentity, pinned?: {
72
+ ready(page: Page): Promise<void>;
73
+ }): Promise<void>;
74
+ export {};