turno-browser 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/CHANGELOG.md +228 -0
  2. package/README.md +205 -16
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +116 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +599 -0
  7. package/dist/api.d.ts +96 -0
  8. package/dist/api.js +88 -0
  9. package/dist/argv.d.ts +55 -3
  10. package/dist/argv.js +190 -10
  11. package/dist/batch.d.ts +19 -0
  12. package/dist/batch.js +148 -0
  13. package/dist/bench.d.ts +1 -1
  14. package/dist/bench.js +21 -5
  15. package/dist/bin/mcp.js +108 -12
  16. package/dist/captcha.d.ts +77 -0
  17. package/dist/captcha.js +333 -0
  18. package/dist/cdp-relay.d.ts +20 -0
  19. package/dist/cdp-relay.js +101 -0
  20. package/dist/chrome-features.d.ts +23 -0
  21. package/dist/chrome-features.js +44 -0
  22. package/dist/detectors.d.ts +11 -0
  23. package/dist/detectors.js +46 -4
  24. package/dist/diagnose.d.ts +45 -0
  25. package/dist/diagnose.js +326 -0
  26. package/dist/doctor.d.ts +85 -0
  27. package/dist/doctor.js +556 -0
  28. package/dist/engine-attach.d.ts +27 -0
  29. package/dist/engine-attach.js +165 -0
  30. package/dist/engine-camoufox.d.ts +32 -0
  31. package/dist/engine-camoufox.js +270 -0
  32. package/dist/engine-lightpanda.d.ts +72 -0
  33. package/dist/engine-lightpanda.js +292 -0
  34. package/dist/engine.d.ts +119 -0
  35. package/dist/engine.js +355 -0
  36. package/dist/flows.d.ts +127 -0
  37. package/dist/flows.js +294 -0
  38. package/dist/governor.d.ts +119 -0
  39. package/dist/governor.js +325 -0
  40. package/dist/health.d.ts +60 -0
  41. package/dist/health.js +86 -0
  42. package/dist/host.d.ts +95 -0
  43. package/dist/host.js +1181 -0
  44. package/dist/human-input.d.ts +84 -0
  45. package/dist/human-input.js +443 -0
  46. package/dist/humanize.d.ts +123 -0
  47. package/dist/humanize.js +241 -0
  48. package/dist/identities.d.ts +23 -10
  49. package/dist/identities.js +45 -37
  50. package/dist/idle-timer.d.ts +12 -0
  51. package/dist/idle-timer.js +25 -0
  52. package/dist/ids.d.ts +9 -0
  53. package/dist/ids.js +34 -0
  54. package/dist/index.d.ts +21 -6
  55. package/dist/index.js +19 -18
  56. package/dist/lifecycle.d.ts +99 -0
  57. package/dist/lifecycle.js +172 -0
  58. package/dist/live-client.d.ts +22 -0
  59. package/dist/live-client.js +93 -0
  60. package/dist/live-page.d.ts +11 -0
  61. package/dist/live-page.js +143 -0
  62. package/dist/live-server.d.ts +173 -0
  63. package/dist/live-server.js +640 -0
  64. package/dist/live.d.ts +120 -0
  65. package/dist/live.js +203 -0
  66. package/dist/login-tool.d.ts +45 -0
  67. package/dist/login-tool.js +233 -0
  68. package/dist/login.d.ts +8 -3
  69. package/dist/login.js +65 -26
  70. package/dist/network-chrome.d.ts +74 -0
  71. package/dist/network-chrome.js +178 -0
  72. package/dist/network.d.ts +125 -0
  73. package/dist/network.js +263 -0
  74. package/dist/opt-in-settings.d.ts +69 -0
  75. package/dist/opt-in-settings.js +151 -0
  76. package/dist/patchright.d.ts +4 -2
  77. package/dist/patchright.js +4 -2
  78. package/dist/recorder.d.ts +88 -0
  79. package/dist/recorder.js +538 -0
  80. package/dist/recordings.d.ts +116 -0
  81. package/dist/recordings.js +474 -0
  82. package/dist/redact.d.ts +34 -0
  83. package/dist/redact.js +135 -0
  84. package/dist/replay.d.ts +20 -0
  85. package/dist/replay.js +382 -0
  86. package/dist/reputation.d.ts +89 -0
  87. package/dist/reputation.js +203 -0
  88. package/dist/resources.d.ts +76 -0
  89. package/dist/resources.js +341 -0
  90. package/dist/runtime-lock.d.ts +59 -0
  91. package/dist/runtime-lock.js +131 -0
  92. package/dist/sealed.d.ts +8 -0
  93. package/dist/sealed.js +96 -0
  94. package/dist/session-export.d.ts +67 -0
  95. package/dist/session-export.js +194 -0
  96. package/dist/session.d.ts +20 -0
  97. package/dist/session.js +30 -0
  98. package/dist/settings.d.ts +246 -0
  99. package/dist/settings.js +530 -0
  100. package/dist/sharing.d.ts +96 -0
  101. package/dist/sharing.js +269 -0
  102. package/dist/snippet.d.ts +8 -0
  103. package/dist/snippet.js +22 -0
  104. package/dist/tab-locks.d.ts +63 -0
  105. package/dist/tab-locks.js +179 -0
  106. package/dist/tools.d.ts +111 -0
  107. package/dist/tools.js +59 -0
  108. package/dist/totp.d.ts +32 -0
  109. package/dist/totp.js +82 -0
  110. package/dist/tuning.d.ts +76 -0
  111. package/dist/tuning.js +69 -0
  112. package/dist/units.d.ts +8 -0
  113. package/dist/units.js +20 -0
  114. package/dist/upstream.d.ts +243 -0
  115. package/dist/upstream.js +46 -0
  116. package/dist/vault.d.ts +91 -0
  117. package/dist/vault.js +273 -0
  118. package/npm-shrinkwrap.json +1074 -3
  119. package/package.json +5 -4
  120. package/dist/paths.d.ts +0 -17
  121. package/dist/paths.js +0 -17
package/dist/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
@@ -0,0 +1,45 @@
1
+ import type { Page } from "patchright-core";
2
+ import type { SecretStore } from "turno-core/secrets";
3
+ import type { IdentityRef } from "./engine.js";
4
+ import type { HumanInput } from "./human-input.js";
5
+ import type { Redactor, VaultGuard } from "./redact.js";
6
+ import type { TurnoTool } from "./tools.js";
7
+ /**
8
+ * `browser_login`: fills a site's username, password and current one-time code from
9
+ * the identity's vault into the sign-in form of the current page. The model names the site; it
10
+ * never sees, sends or receives a value:
11
+ *
12
+ * - The page (its main frame) must be on one of the origins the site was stored with, and only
13
+ * frames of those origins are filled, so a model led to another site cannot spend the
14
+ * credentials there.
15
+ * - A password goes only into `<input type="password">`; a username and a code only into text
16
+ * inputs. A field the model names by ref must pass the same check.
17
+ * - Before anything is filled, the values join the host's redactor, so no result or error of
18
+ * this server shows them from then on, and the page is held by the vault guard, which refuses
19
+ * the script tools on it until it navigates.
20
+ * - It does not submit unless the identity chose `turno browser vault submit <id> auto`: the
21
+ * model clicks the sign-in button itself, as a separate, visible step.
22
+ */
23
+ /** What the host gives `browser_login`. */
24
+ export interface VaultAccess {
25
+ identity: IdentityRef;
26
+ redactor: Redactor;
27
+ guard: VaultGuard;
28
+ /** The secret store (tests inject a fake); default: this machine's. */
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;
41
+ }
42
+ /** The tool. Its schema is built on first use, so importing the registry does not load the bundle. */
43
+ export declare function loginTool(): TurnoTool;
44
+ /** What of the server's config records page content a filled value would end up in. */
45
+ export declare function recordingReason(config: unknown): string | undefined;
@@ -0,0 +1,233 @@
1
+ import { totp, totpSecondsLeft } from "./totp.js";
2
+ import { upstream } from "./upstream.js";
3
+ import { VaultError, originAllowed, readCredential, vaultSite } from "./vault.js";
4
+ const TEXT = ':not([type="password"]):not([type="hidden"]):not([type="checkbox"]):not([type="radio"]):not([type="submit"]):not([type="button"])';
5
+ const SELECTORS = {
6
+ password: 'input[type="password"]',
7
+ username: [
8
+ 'input[autocomplete~="username" i]',
9
+ 'input[type="email"]',
10
+ 'input[autocomplete~="email" i]',
11
+ 'input[name*="user" i]',
12
+ 'input[id*="user" i]',
13
+ 'input[name*="email" i]',
14
+ 'input[id*="email" i]',
15
+ 'input[name*="login" i]',
16
+ 'input[id*="login" i]',
17
+ 'input[name="identifier" i]',
18
+ ]
19
+ .map((s) => `${s}${TEXT}`)
20
+ .join(", "),
21
+ code: [
22
+ 'input[autocomplete="one-time-code" i]',
23
+ 'input[name*="otp" i]',
24
+ 'input[id*="otp" i]',
25
+ 'input[name*="totp" i]',
26
+ 'input[name*="2fa" i]',
27
+ 'input[name*="mfa" i]',
28
+ 'input[name*="code" i]',
29
+ 'input[id*="code" i]',
30
+ ]
31
+ .map((s) => `${s}${TEXT}`)
32
+ .join(", "),
33
+ };
34
+ /** How long a filled one-time code stays redacted. */
35
+ const CODE_REDACT_MS = 10 * 60_000;
36
+ /** A code with less than this left is not used; the tool waits for the next one. */
37
+ const MIN_CODE_SECONDS = 3;
38
+ function schema() {
39
+ const z = upstream().utils.z;
40
+ const ref = (what) => z
41
+ .string()
42
+ .optional()
43
+ .describe(`Ref (from the page snapshot) or selector of the ${what} field, only when the tool does not find it by itself`);
44
+ return {
45
+ name: "browser_login",
46
+ title: "Fill a sign-in form from the vault",
47
+ description: [
48
+ "Fill the sign-in form of the current page with the username, password and current one-time code stored for a site in this browser identity's vault.",
49
+ "You name the site; the values are never shown to you, and they are hidden from every later result of this server.",
50
+ "The current page must be on the site's own sign-in page (the origins it was stored with).",
51
+ "Fields found on the page are filled (a two-step sign-in needs one call per step). It does not submit the form unless the identity allows it: click the sign-in button yourself afterwards.",
52
+ "The person adds credentials with `turno browser vault add <identity> <site>`.",
53
+ ].join(" "),
54
+ inputSchema: z.object({
55
+ site: z.string().describe("The site key in the vault, for example github"),
56
+ usernameField: ref("username"),
57
+ passwordField: ref("password"),
58
+ codeField: ref("one-time code"),
59
+ }),
60
+ type: "action",
61
+ };
62
+ }
63
+ /** The element's type and the origin of its frame, to check a field before a value goes in. */
64
+ async function describeField(locator) {
65
+ return await locator
66
+ .evaluate((el) => ({
67
+ tag: el.tagName.toLowerCase(),
68
+ type: (el.type || "text").toLowerCase(),
69
+ origin: el.ownerDocument.location.origin,
70
+ }), undefined, {
71
+ timeout: 2_000,
72
+ })
73
+ .catch(() => undefined);
74
+ }
75
+ const TEXT_TYPES = new Set(["text", "email", "tel", "number", "search", "url"]);
76
+ function fits(field, d) {
77
+ if (d.tag !== "input")
78
+ return false;
79
+ return field === "password" ? d.type === "password" : TEXT_TYPES.has(d.type);
80
+ }
81
+ /** The first visible field of this kind in the allowed frames, main frame first. */
82
+ async function findField(frames, field) {
83
+ for (const frame of frames) {
84
+ const locator = frame.locator(SELECTORS[field]).filter({ visible: true }).first();
85
+ if ((await locator.count().catch(() => 0)) > 0)
86
+ return locator;
87
+ }
88
+ return undefined;
89
+ }
90
+ /** A field the model named: a snapshot ref or a selector, checked like a found one. */
91
+ async function namedField(page, target, field, site) {
92
+ const locator = (/^(f\d+)?e\d+$/.test(target) ? page.getByRef(target) : page.locator(target)).first();
93
+ const d = await describeField(locator);
94
+ if (!d)
95
+ throw new VaultError(`the ${field} field ${target} is not on the page; take a new snapshot`);
96
+ if (!fits(field, d))
97
+ throw new VaultError(`${target} is a ${d.tag}${d.tag === "input" ? ` of type ${d.type}` : ""}, not a ${field === "password" ? "password field" : "text field"}; the ${field} goes only into one`);
98
+ if (!site.origins.includes(d.origin))
99
+ throw new VaultError(`${target} is in a frame of ${d.origin}, not one of the site's origins (${site.origins.join(", ")})`);
100
+ return locator;
101
+ }
102
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
103
+ /** The tool. Its schema is built on first use, so importing the registry does not load the bundle. */
104
+ export function loginTool() {
105
+ let built;
106
+ return {
107
+ get schema() {
108
+ built ??= schema();
109
+ return built;
110
+ },
111
+ async handle(ctx, params) {
112
+ const vault = ctx.vault;
113
+ if (!vault)
114
+ throw new VaultError("browser_login needs a browser identity: this server runs without --identity");
115
+ const recording = recordingReason(ctx.config);
116
+ if (recording)
117
+ throw new VaultError(`browser_login is off while this server records ${recording} (it would keep the filled values); start it without that option`);
118
+ const { id, env } = vault.identity;
119
+ const siteKey = params.site;
120
+ const found = vaultSite(id, siteKey, env);
121
+ if (!found)
122
+ throw new VaultError(`identity "${id}" has no credentials for "${siteKey}" in its vault; the person adds them with: turno browser vault add ${id} ${siteKey} --url <sign-in page>`);
123
+ const { site, submit } = found;
124
+ const page = ctx.stock?.currentPage();
125
+ if (!page)
126
+ throw new VaultError("no page is open; navigate to the sign-in page first");
127
+ if (!originAllowed(site, page.url())) {
128
+ throw new VaultError(`this page is on ${safeOrigin(page.url())}, not on an origin "${siteKey}" was stored for (${site.origins.join(", ")}); navigate to its sign-in page first`);
129
+ }
130
+ const frames = page.frames().filter((f) => originAllowed(site, f.url()));
131
+ const fields = new Map();
132
+ for (const field of ["username", "password", "code"]) {
133
+ const named = params[`${field}Field`];
134
+ const locator = named ? await namedField(page, named, field, site) : await findField(frames, field);
135
+ if (locator)
136
+ fields.set(field, locator);
137
+ }
138
+ if (!fields.size) {
139
+ throw new VaultError(`found no username, password or one-time code field on ${safeOrigin(page.url())}; take a snapshot and pass the field's ref as usernameField, passwordField or codeField`);
140
+ }
141
+ const credential = await readCredential(id, siteKey, {
142
+ env,
143
+ ...(vault.store ? { store: vault.store } : {}),
144
+ });
145
+ const skipped = [];
146
+ let code;
147
+ if (fields.has("code")) {
148
+ if (!credential.totp) {
149
+ fields.delete("code");
150
+ skipped.push("the one-time code (no TOTP secret is stored for this site)");
151
+ }
152
+ else {
153
+ const left = totpSecondsLeft(credential.totp);
154
+ if (left < MIN_CODE_SECONDS)
155
+ await sleep(left * 1000 + 200);
156
+ code = totp(credential.totp);
157
+ }
158
+ }
159
+ await vault.beforeFill?.(page);
160
+ // Redact first: from here on no result or error of this server shows a value.
161
+ vault.redactor.add(credential.username, `${siteKey} username`);
162
+ vault.redactor.add(credential.password, `${siteKey} password`);
163
+ if (code)
164
+ vault.redactor.add(code, `${siteKey} one-time code`, CODE_REDACT_MS);
165
+ vault.guard.mark(page);
166
+ const values = {
167
+ username: credential.username,
168
+ password: credential.password,
169
+ code,
170
+ };
171
+ const filled = [];
172
+ let last;
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;
177
+ try {
178
+ await locator.fill(values[field], { timeout: 5_000 });
179
+ }
180
+ catch (error) {
181
+ throw new VaultError(`could not fill the ${field} field: ${vault.redactor.text(firstLine(error))}`);
182
+ }
183
+ filled.push(field);
184
+ last = locator;
185
+ }
186
+ const names = filled.map((f) => (f === "code" ? "one-time code" : f));
187
+ const lines = [
188
+ `Filled the ${list(names)} of "${siteKey}" from the vault of identity "${id}" on ${safeOrigin(page.url())}. The values are hidden as [vault: ...] in every result.`,
189
+ ];
190
+ if (skipped.length)
191
+ lines.push(`Not filled: ${skipped.join("; ")}.`);
192
+ if (submit === "auto" && last) {
193
+ await last.press("Enter", { timeout: 5_000 });
194
+ await page.waitForLoadState("domcontentloaded", { timeout: 10_000 }).catch(() => { });
195
+ lines.push("Submitted the form (this identity submits sign-ins itself). Check the page below for the result.");
196
+ }
197
+ else {
198
+ lines.push("Nothing was submitted: click the sign-in button yourself (it is in the snapshot below).");
199
+ }
200
+ const snapshot = ctx.stock ? await ctx.stock.call("browser_snapshot", {}, { snapshot: true }) : undefined;
201
+ const text = [`### Result`, ...lines].join("\n");
202
+ return { content: [{ type: "text", text }, ...(snapshot?.content ?? [])] };
203
+ },
204
+ };
205
+ }
206
+ /** What of the server's config records page content a filled value would end up in. */
207
+ export function recordingReason(config) {
208
+ const c = config;
209
+ if (c.saveSession)
210
+ return "the session (--save-session)";
211
+ if (c.saveVideo || c.browser?.contextOptions?.recordVideo)
212
+ return "video (--save-video)";
213
+ if (c.browser?.contextOptions?.recordHar)
214
+ return "a HAR file (recordHar)";
215
+ if (c.capabilities?.includes("devtools"))
216
+ return "traces (the devtools capability)";
217
+ return undefined;
218
+ }
219
+ function list(items) {
220
+ return items.length <= 1 ? (items[0] ?? "") : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
221
+ }
222
+ function safeOrigin(url) {
223
+ try {
224
+ return new URL(url).origin;
225
+ }
226
+ catch {
227
+ return "this page";
228
+ }
229
+ }
230
+ function firstLine(error) {
231
+ return String(error?.message ?? error).split("\n")[0] ?? "";
232
+ }
233
+ //# sourceMappingURL=login-tool.js.map
package/dist/login.d.ts CHANGED
@@ -4,8 +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
8
- * server (Chrome channel, no fixed viewport), and resolves when the user closes the last
9
- * window or quits Chrome. Used once per site so the user signs in by hand.
7
+ * Opens the identity's persistent Chrome headed, with the same launch settings as the MCP
8
+ * server (Chrome channel, no fixed viewport, the identity's languages and time zone), and
9
+ * resolves when the user closes the last window or quits Chrome. Used once per site so the user
10
+ * signs in by hand. It holds the identity's runtime lock while the window is open, and clears
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.
10
15
  */
11
16
  export declare function loginIdentity(id: string, options?: LoginOptions): Promise<void>;