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.
- package/CHANGELOG.md +98 -0
- package/README.md +32 -3
- package/dist/act-model.d.ts +85 -0
- package/dist/act-model.js +116 -0
- package/dist/act.d.ts +37 -0
- package/dist/act.js +599 -0
- package/dist/api.d.ts +29 -2
- package/dist/api.js +29 -2
- package/dist/argv.d.ts +16 -2
- package/dist/argv.js +100 -3
- package/dist/batch.d.ts +5 -0
- package/dist/batch.js +3 -3
- package/dist/bin/mcp.js +58 -1
- package/dist/captcha.d.ts +77 -0
- package/dist/captcha.js +333 -0
- package/dist/cdp-relay.d.ts +20 -0
- package/dist/cdp-relay.js +101 -0
- package/dist/chrome-features.d.ts +23 -0
- package/dist/chrome-features.js +44 -0
- package/dist/diagnose.d.ts +7 -0
- package/dist/diagnose.js +61 -6
- package/dist/doctor.d.ts +37 -3
- package/dist/doctor.js +230 -5
- package/dist/engine-attach.d.ts +27 -0
- package/dist/engine-attach.js +165 -0
- package/dist/engine-camoufox.d.ts +32 -0
- package/dist/engine-camoufox.js +270 -0
- package/dist/engine-lightpanda.d.ts +72 -0
- package/dist/engine-lightpanda.js +292 -0
- package/dist/engine.d.ts +63 -11
- package/dist/engine.js +104 -28
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +42 -7
- package/dist/governor.js +82 -32
- package/dist/host.d.ts +17 -2
- package/dist/host.js +618 -41
- package/dist/human-input.d.ts +84 -0
- package/dist/human-input.js +443 -0
- package/dist/humanize.d.ts +123 -0
- package/dist/humanize.js +241 -0
- package/dist/identities.js +2 -0
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/index.d.ts +8 -3
- package/dist/index.js +5 -1
- package/dist/lifecycle.d.ts +9 -1
- package/dist/lifecycle.js +9 -1
- package/dist/live-client.d.ts +22 -0
- package/dist/live-client.js +93 -0
- package/dist/live-page.d.ts +11 -0
- package/dist/live-page.js +143 -0
- package/dist/live-server.d.ts +173 -0
- package/dist/live-server.js +640 -0
- package/dist/live.d.ts +120 -0
- package/dist/live.js +203 -0
- package/dist/login-tool.d.ts +13 -0
- package/dist/login-tool.js +5 -1
- package/dist/login.d.ts +4 -1
- package/dist/login.js +11 -2
- package/dist/network-chrome.d.ts +74 -0
- package/dist/network-chrome.js +178 -0
- package/dist/network.d.ts +125 -0
- package/dist/network.js +263 -0
- package/dist/opt-in-settings.d.ts +69 -0
- package/dist/opt-in-settings.js +151 -0
- package/dist/recorder.d.ts +88 -0
- package/dist/recorder.js +538 -0
- package/dist/recordings.d.ts +116 -0
- package/dist/recordings.js +474 -0
- package/dist/redact.d.ts +7 -0
- package/dist/redact.js +18 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +382 -0
- package/dist/reputation.d.ts +24 -2
- package/dist/reputation.js +63 -17
- package/dist/session-export.js +1 -1
- package/dist/session.d.ts +10 -2
- package/dist/session.js +10 -2
- package/dist/settings.d.ts +104 -2
- package/dist/settings.js +204 -6
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -2
- package/dist/snippet.js +10 -4
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +38 -0
- package/dist/tools.js +20 -1
- package/dist/tuning.d.ts +14 -0
- package/dist/tuning.js +9 -0
- package/dist/upstream.d.ts +11 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
package/dist/engine.d.ts
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
|
-
import type { BrowserContext } from "patchright-core";
|
|
1
|
+
import type { BrowserContext, Page } from "patchright-core";
|
|
2
|
+
import { type AttachTarget } from "./engine-attach.js";
|
|
3
|
+
import { type IdentitySettings } from "./settings.js";
|
|
2
4
|
import { type Tuning } from "./tuning.js";
|
|
3
5
|
import { type ClientInfo, type IdleTimerLike, type McpConfig } from "./upstream.js";
|
|
4
6
|
/**
|
|
5
7
|
* Where the browser context behind an MCP session comes from. The host asks an
|
|
6
8
|
* engine for a context when a session first needs the browser, and again after the browser
|
|
7
|
-
* closed (idle limit, `browser_close`); it never launches a browser any other way.
|
|
9
|
+
* closed (idle limit, `browser_close`); it never launches a browser any other way. This module
|
|
10
|
+
* and the `engine-*.ts` modules are the only code that knows how each engine starts.
|
|
8
11
|
*
|
|
9
12
|
* - `chrome`: the default. turno launches the installed Chrome itself, as a Patchright
|
|
10
13
|
* persistent context on the profile it chose (the identity's, or a temporary one), with the
|
|
@@ -12,11 +15,18 @@ import { type ClientInfo, type IdleTimerLike, type McpConfig } from "./upstream.
|
|
|
12
15
|
* - `upstream`: every other mode (`--isolated`, `--cdp-endpoint`, `--endpoint`, `--extension`,
|
|
13
16
|
* `--shared-browser-context`, another browser than Chromium), handed to upstream's
|
|
14
17
|
* `createBrowserWithInfo` exactly as the stock program does.
|
|
18
|
+
* - `lightpanda`: read mode on Lightpanda (`engine-lightpanda.ts`), chosen explicitly.
|
|
19
|
+
* - `attach`: the Chrome the user already has open (`engine-attach.ts`), chosen explicitly.
|
|
20
|
+
* - `camoufox`: Camoufox, a Firefox build, on stock Playwright (`engine-camoufox.ts`), chosen
|
|
21
|
+
* explicitly.
|
|
15
22
|
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
23
|
+
* Which one runs is decided at every launch (`engineChoice`): a server flag (`--engine`,
|
|
24
|
+
* `--attach`) wins over identity.json (`engine`, `attach`), which is read at every launch like
|
|
25
|
+
* the rest of it; without either, the config decides between `chrome` and `upstream`. Another
|
|
26
|
+
* engine is one more `Engine` and one more case in `createEngine`; the host only sees
|
|
27
|
+
* `LaunchedBrowser`.
|
|
18
28
|
*/
|
|
19
|
-
type EngineId = "chrome" | "upstream";
|
|
29
|
+
type EngineId = "chrome" | "upstream" | "lightpanda" | "attach" | "camoufox";
|
|
20
30
|
export interface LaunchedBrowser {
|
|
21
31
|
engine: EngineId;
|
|
22
32
|
/** The context the tools drive. */
|
|
@@ -32,6 +42,14 @@ export interface LaunchedBrowser {
|
|
|
32
42
|
isOpen(): boolean;
|
|
33
43
|
/** Closes the browser after the configured time without a tool call. */
|
|
34
44
|
idleTimer?: IdleTimerLike;
|
|
45
|
+
/**
|
|
46
|
+
* True when the browser is the user's own (attach mode): the host opens a tab of its own as
|
|
47
|
+
* the current tab, the tab governor touches only the agent's tabs, and nothing is brought to
|
|
48
|
+
* the front.
|
|
49
|
+
*/
|
|
50
|
+
userBrowser?: boolean;
|
|
51
|
+
/** Marks a page as opened by the agent, so `close` closes it (attach mode). */
|
|
52
|
+
own?(page: Page): void;
|
|
35
53
|
}
|
|
36
54
|
export interface LaunchRequest {
|
|
37
55
|
config: McpConfig;
|
|
@@ -44,6 +62,8 @@ export interface LaunchRequest {
|
|
|
44
62
|
identity?: IdentityRef;
|
|
45
63
|
/** How to run this browser; the chrome engine applies `backgroundThrottling`. */
|
|
46
64
|
tuning?: Tuning;
|
|
65
|
+
/** Hides a secret the launch read (proxy credentials) from every tool result. */
|
|
66
|
+
secret?: (value: string, label: string) => void;
|
|
47
67
|
}
|
|
48
68
|
/** A browser identity as the host knows it: its id and the environment that locates its files. */
|
|
49
69
|
export interface IdentityRef {
|
|
@@ -53,15 +73,47 @@ export interface IdentityRef {
|
|
|
53
73
|
export interface Engine {
|
|
54
74
|
id: EngineId;
|
|
55
75
|
launch(request: LaunchRequest): Promise<LaunchedBrowser>;
|
|
76
|
+
/**
|
|
77
|
+
* Why this engine does not run a tool, checked before the call reaches (or launches) the
|
|
78
|
+
* browser; undefined when it runs it. For the identity's engine, `identity` says which one.
|
|
79
|
+
*/
|
|
80
|
+
refuse?(tool: string, identity?: IdentityRef): string | undefined;
|
|
56
81
|
}
|
|
57
82
|
/** True when the config asks for the browser the `chrome` engine launches. */
|
|
58
83
|
export declare function usesChromeEngine(config: McpConfig): boolean;
|
|
59
|
-
/**
|
|
60
|
-
* Every mode turno does not launch itself goes through upstream's `createBrowserWithInfo`,
|
|
61
|
-
* with the session handling of upstream's MCP program (`program.ts`): sessions share one
|
|
62
|
-
* browser for `--shared-browser-context` and `--isolated`, and the last one to leave closes it.
|
|
63
|
-
*/
|
|
64
|
-
export declare function createUpstreamEngine(): Engine;
|
|
65
84
|
/** The engine for this config. */
|
|
66
85
|
export declare function selectEngine(config: McpConfig, fallback: Engine): Engine;
|
|
86
|
+
/** The `turno-browser-mcp` flags that pick an engine; each wins over identity.json. */
|
|
87
|
+
export interface EngineFlags {
|
|
88
|
+
engine?: "chrome" | "lightpanda" | "camoufox";
|
|
89
|
+
/** An attach target (`parseAttachTarget`). */
|
|
90
|
+
attach?: string;
|
|
91
|
+
}
|
|
92
|
+
/** The engine one launch uses, before the config decides between `chrome` and `upstream`. */
|
|
93
|
+
export type EngineChoice = {
|
|
94
|
+
kind: "default";
|
|
95
|
+
} | {
|
|
96
|
+
kind: "lightpanda";
|
|
97
|
+
} | {
|
|
98
|
+
kind: "camoufox";
|
|
99
|
+
} | {
|
|
100
|
+
kind: "attach";
|
|
101
|
+
target: AttachTarget;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Flags first, then identity.json. A flag of either kind replaces both keys of identity.json:
|
|
105
|
+
* `--engine chrome` turns an identity's attach or read mode off for that server.
|
|
106
|
+
*/
|
|
107
|
+
export declare function engineChoice(flags: EngineFlags, settings: Pick<IdentitySettings, "engine" | "attach"> | undefined): EngineChoice;
|
|
108
|
+
/**
|
|
109
|
+
* The host's engine: at every launch it reads the identity's settings and the flags, and hands
|
|
110
|
+
* the launch to `lightpanda`, `attach`, or the engine the config selects.
|
|
111
|
+
*/
|
|
112
|
+
/**
|
|
113
|
+
* Why an engine cannot run with these settings, if it cannot: attach mode keeps one agent's tabs
|
|
114
|
+
* apart from the user's, not several sessions apart from each other, and read mode has no
|
|
115
|
+
* layout for human-like input to move over.
|
|
116
|
+
*/
|
|
117
|
+
export declare function tuningClash(engine: string, tuning: Pick<Tuning, "sharing" | "humanize">): string | undefined;
|
|
118
|
+
export declare function createEngine(config: McpConfig, flags?: EngineFlags, fallback?: Engine): Engine;
|
|
67
119
|
export {};
|
package/dist/engine.js
CHANGED
|
@@ -1,29 +1,16 @@
|
|
|
1
1
|
import { resolve } from "node:path";
|
|
2
|
+
import { storagePartitioningArgs } from "./chrome-features.js";
|
|
3
|
+
import { createAttachEngine, parseAttachTarget } from "./engine-attach.js";
|
|
4
|
+
import { createCamoufoxEngine } from "./engine-camoufox.js";
|
|
5
|
+
import { createLightpandaEngine } from "./engine-lightpanda.js";
|
|
2
6
|
import { findProfileChrome, readLockPid } from "./lifecycle.js";
|
|
7
|
+
import { chromeNetwork, pinUserAgent, verifyCoherence } from "./network-chrome.js";
|
|
8
|
+
import { networkEngineClash } from "./network.js";
|
|
3
9
|
import { acquireRuntimeLock } from "./runtime-lock.js";
|
|
4
|
-
import { keychainArgs, launchSettings, readIdentitySettings, systemTimezone } from "./settings.js";
|
|
10
|
+
import { keychainArgs, launchSettings, readIdentitySettings, recordEngineClash, systemTimezone, } from "./settings.js";
|
|
5
11
|
import { launchTuning } from "./tuning.js";
|
|
12
|
+
import { IdleTimer, idleMs } from "./idle-timer.js";
|
|
6
13
|
import { playwright, upstream } from "./upstream.js";
|
|
7
|
-
/** Upstream's default idle limit for a headless browser it owns (`defaultIdleTimeout`). */
|
|
8
|
-
const HEADLESS_IDLE_MS = 60 * 60 * 1000;
|
|
9
|
-
/** Upstream's `IdleTimer`: every tool call restarts the countdown. */
|
|
10
|
-
class IdleTimer {
|
|
11
|
-
ms;
|
|
12
|
-
onIdle;
|
|
13
|
-
timer;
|
|
14
|
-
constructor(ms, onIdle) {
|
|
15
|
-
this.ms = ms;
|
|
16
|
-
this.onIdle = onIdle;
|
|
17
|
-
}
|
|
18
|
-
poke() {
|
|
19
|
-
this.dispose();
|
|
20
|
-
this.timer = setTimeout(this.onIdle, this.ms);
|
|
21
|
-
}
|
|
22
|
-
dispose() {
|
|
23
|
-
clearTimeout(this.timer);
|
|
24
|
-
this.timer = undefined;
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
14
|
/** True when the config asks for the browser the `chrome` engine launches. */
|
|
28
15
|
export function usesChromeEngine(config) {
|
|
29
16
|
const b = config.browser;
|
|
@@ -87,17 +74,21 @@ function profileInUse(identity, userDataDir) {
|
|
|
87
74
|
* records Chrome's PID and process group in it, gives it back when Chrome closes, and applies
|
|
88
75
|
* identity.json: languages and locale as Chrome flags, the time zone as `timezoneId`. With
|
|
89
76
|
* `backgroundThrottling` it drops Playwright's three anti-throttling switches and
|
|
90
|
-
* turns off its focus emulation (`launchTuning`).
|
|
77
|
+
* turns off its focus emulation (`launchTuning`). Third-party storage partitioning, which
|
|
78
|
+
* Playwright turns off, stays on (`chrome-features.ts`).
|
|
91
79
|
*/
|
|
92
80
|
const chromeEngine = {
|
|
93
81
|
id: "chrome",
|
|
94
|
-
async launch({ config, clientInfo, title, identity, tuning }) {
|
|
82
|
+
async launch({ config, clientInfo, title, identity, tuning, secret }) {
|
|
95
83
|
const userDataDir = config.browser.userDataDir;
|
|
96
84
|
if (userDataDir === undefined)
|
|
97
85
|
throw new Error("the chrome engine needs a profile directory");
|
|
98
86
|
const { tools } = upstream();
|
|
99
87
|
const tracesDir = resolve(tools.outputDir({ config, cwd: clientInfo.cwd }), "traces");
|
|
100
88
|
const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
|
|
89
|
+
// Proxy credentials and the coherent user agent are settled before the lock: a missing
|
|
90
|
+
// secret or an unknown Chrome version stops here, with nothing to undo.
|
|
91
|
+
const network = settings ? await chromeNetwork(settings, config, identity.env, secret ?? (() => { })) : undefined;
|
|
101
92
|
const held = identity ? acquireRuntimeLock(identity.id, identity.env, { holder: "mcp" }) : undefined;
|
|
102
93
|
let context;
|
|
103
94
|
let browser;
|
|
@@ -108,19 +99,23 @@ const chromeEngine = {
|
|
|
108
99
|
const userArgs = config.browser.launchOptions.args ?? [];
|
|
109
100
|
const applied = launchSettings(settings, userArgs, systemTimezone(), config.browser.contextOptions);
|
|
110
101
|
const tuned = tuning ? launchTuning(tuning) : { ignoreDefaultArgs: [], contextOptions: {} };
|
|
102
|
+
// Chrome's third-party storage partitioning stays on, as in a person's Chrome (`chrome-features.ts`).
|
|
103
|
+
const partitioning = config.browser.browserName === "chromium" && ignore !== true ? storagePartitioningArgs() : undefined;
|
|
111
104
|
const launchOptions = {
|
|
112
105
|
tracesDir,
|
|
113
106
|
...config.browser.launchOptions,
|
|
114
107
|
...tuned.contextOptions,
|
|
115
108
|
...config.browser.contextOptions,
|
|
116
|
-
...(
|
|
109
|
+
args: [...(partitioning?.args ?? []), ...userArgs, ...applied.args, ...(network?.args ?? [])],
|
|
117
110
|
...(applied.timezoneId ? { timezoneId: applied.timezoneId } : {}),
|
|
111
|
+
...(network?.proxy ? { proxy: network.proxy } : {}),
|
|
118
112
|
handleSIGINT: false,
|
|
119
113
|
handleSIGTERM: false,
|
|
120
114
|
ignoreDefaultArgs: ignore === true
|
|
121
115
|
? true
|
|
122
116
|
: [
|
|
123
117
|
"--disable-extensions",
|
|
118
|
+
...(partitioning?.ignoreDefaultArgs ?? []),
|
|
124
119
|
...tuned.ignoreDefaultArgs,
|
|
125
120
|
...(keychainArgs(settings).ignoreDefaultArgs ?? []),
|
|
126
121
|
...(Array.isArray(ignore) ? ignore : []),
|
|
@@ -134,6 +129,9 @@ const chromeEngine = {
|
|
|
134
129
|
}
|
|
135
130
|
browser = context.browser();
|
|
136
131
|
try {
|
|
132
|
+
const pinned = network?.pin ? pinUserAgent(context, network.pin) : undefined;
|
|
133
|
+
if (network?.verify)
|
|
134
|
+
await verifyCoherence(context, browser.version(), network.verify, pinned);
|
|
137
135
|
await browser.bind(title, { workspaceDir: clientInfo.cwd });
|
|
138
136
|
}
|
|
139
137
|
catch (err) {
|
|
@@ -146,10 +144,10 @@ const chromeEngine = {
|
|
|
146
144
|
throw err;
|
|
147
145
|
}
|
|
148
146
|
let closing = false;
|
|
149
|
-
const
|
|
147
|
+
const ms = idleMs(config);
|
|
150
148
|
let idleTimer;
|
|
151
|
-
if (
|
|
152
|
-
const timer = new IdleTimer(
|
|
149
|
+
if (ms) {
|
|
150
|
+
const timer = new IdleTimer(ms, () => {
|
|
153
151
|
closing = true;
|
|
154
152
|
void browser.close().catch(() => { });
|
|
155
153
|
});
|
|
@@ -194,7 +192,7 @@ function remoteConnectOptions(config) {
|
|
|
194
192
|
* with the session handling of upstream's MCP program (`program.ts`): sessions share one
|
|
195
193
|
* browser for `--shared-browser-context` and `--isolated`, and the last one to leave closes it.
|
|
196
194
|
*/
|
|
197
|
-
|
|
195
|
+
function createUpstreamEngine() {
|
|
198
196
|
let shared;
|
|
199
197
|
let clients = 0;
|
|
200
198
|
return {
|
|
@@ -276,4 +274,82 @@ export function createUpstreamEngine() {
|
|
|
276
274
|
export function selectEngine(config, fallback) {
|
|
277
275
|
return usesChromeEngine(config) ? chromeEngine : fallback;
|
|
278
276
|
}
|
|
277
|
+
/**
|
|
278
|
+
* Flags first, then identity.json. A flag of either kind replaces both keys of identity.json:
|
|
279
|
+
* `--engine chrome` turns an identity's attach or read mode off for that server.
|
|
280
|
+
*/
|
|
281
|
+
export function engineChoice(flags, settings) {
|
|
282
|
+
const fromFlags = flags.engine !== undefined || flags.attach !== undefined;
|
|
283
|
+
const engine = fromFlags ? flags.engine : settings?.engine;
|
|
284
|
+
const attach = fromFlags ? flags.attach : settings?.attach;
|
|
285
|
+
if (attach !== undefined) {
|
|
286
|
+
if (engine === "lightpanda" || engine === "camoufox")
|
|
287
|
+
throw new Error(`attach and the ${engine} engine do not go together: pick one`);
|
|
288
|
+
const target = parseAttachTarget(attach);
|
|
289
|
+
if ("error" in target)
|
|
290
|
+
throw new Error(target.error);
|
|
291
|
+
return { kind: "attach", target };
|
|
292
|
+
}
|
|
293
|
+
if (engine === "lightpanda")
|
|
294
|
+
return { kind: "lightpanda" };
|
|
295
|
+
return engine === "camoufox" ? { kind: "camoufox" } : { kind: "default" };
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* The host's engine: at every launch it reads the identity's settings and the flags, and hands
|
|
299
|
+
* the launch to `lightpanda`, `attach`, or the engine the config selects.
|
|
300
|
+
*/
|
|
301
|
+
/**
|
|
302
|
+
* Why an engine cannot run with these settings, if it cannot: attach mode keeps one agent's tabs
|
|
303
|
+
* apart from the user's, not several sessions apart from each other, and read mode has no
|
|
304
|
+
* layout for human-like input to move over.
|
|
305
|
+
*/
|
|
306
|
+
export function tuningClash(engine, tuning) {
|
|
307
|
+
if (engine === "attach" && tuning.sharing === "tabs")
|
|
308
|
+
return '"sharing": "tabs" does not go with attach mode: in your own Chrome turno keeps one agent\'s tabs apart from yours, not several sessions apart. Turn one off (--sharing session, or --attach "")';
|
|
309
|
+
if (engine === "lightpanda" && tuning.humanize.level !== "off")
|
|
310
|
+
return "humanize does not go with read mode: Lightpanda lays out no page, so there is no pointer path or scroll to play. Turn one off (--humanize off, or --engine chrome)";
|
|
311
|
+
return undefined;
|
|
312
|
+
}
|
|
313
|
+
export function createEngine(config, flags = {}, fallback) {
|
|
314
|
+
const base = selectEngine(config, fallback ?? createUpstreamEngine());
|
|
315
|
+
const lightpanda = createLightpandaEngine();
|
|
316
|
+
const camoufox = createCamoufoxEngine();
|
|
317
|
+
const choose = (identity) => {
|
|
318
|
+
const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
|
|
319
|
+
const choice = engineChoice(flags, settings);
|
|
320
|
+
if (choice.kind === "lightpanda")
|
|
321
|
+
return lightpanda;
|
|
322
|
+
if (choice.kind === "camoufox")
|
|
323
|
+
return camoufox;
|
|
324
|
+
if (choice.kind === "attach")
|
|
325
|
+
return createAttachEngine(choice.target);
|
|
326
|
+
return base;
|
|
327
|
+
};
|
|
328
|
+
return {
|
|
329
|
+
id: base.id,
|
|
330
|
+
launch: async (request) => {
|
|
331
|
+
const engine = choose(request.identity);
|
|
332
|
+
const settings = request.identity ? readIdentitySettings(request.identity.id, request.identity.env) : undefined;
|
|
333
|
+
const record = settings?.record;
|
|
334
|
+
// A flag can pick an engine that identity.json's other keys do not go with: refused here,
|
|
335
|
+
// before anything starts.
|
|
336
|
+
const clash = (request.tuning ? tuningClash(engine.id, request.tuning) : undefined) ??
|
|
337
|
+
(record ? recordEngineClash(engine.id, record) : undefined) ??
|
|
338
|
+
(settings ? networkEngineClash(engine.id, settings) : undefined);
|
|
339
|
+
if (clash)
|
|
340
|
+
throw new Error(clash);
|
|
341
|
+
return await engine.launch(request);
|
|
342
|
+
},
|
|
343
|
+
refuse(tool, identity) {
|
|
344
|
+
let engine;
|
|
345
|
+
try {
|
|
346
|
+
engine = choose(identity);
|
|
347
|
+
}
|
|
348
|
+
catch {
|
|
349
|
+
return undefined; // the launch reports a bad identity.json or flag
|
|
350
|
+
}
|
|
351
|
+
return engine.refuse?.(tool, identity);
|
|
352
|
+
},
|
|
353
|
+
};
|
|
354
|
+
}
|
|
279
355
|
//# sourceMappingURL=engine.js.map
|
package/dist/flows.d.ts
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Saved flows: the browser actions a session made on an identity, stored so that
|
|
3
|
+
* `browser_replay` (and `turno browser replay`) can run them again without the model working
|
|
4
|
+
* the page out a second time. One JSON file per flow, under `<data>/browser/flows/<id>/`, next
|
|
5
|
+
* to the identity's other files and never inside its Chrome profile.
|
|
6
|
+
*
|
|
7
|
+
* What a flow file holds, and what it never holds:
|
|
8
|
+
*
|
|
9
|
+
* - Each step names a browser tool and its arguments. An element is kept as several
|
|
10
|
+
* locators (Playwright's own pick, role and accessible name, visible text, a CSS path), tried
|
|
11
|
+
* in that order on replay, plus the snapshot ref it had (for reading only: refs change with
|
|
12
|
+
* every snapshot, so replay never uses one).
|
|
13
|
+
* - Text typed into a field is a parameter (`{ "$param": "email" }`). A non-sensitive one keeps
|
|
14
|
+
* what was typed as its default; a sensitive one (a password field, a one-time code, a card
|
|
15
|
+
* number, a value the agent marked) keeps no value at all, so replay needs it again.
|
|
16
|
+
* - A vault sign-in is a `browser_login` step with the site's name only: the values stay in
|
|
17
|
+
* the secret store and are read again at replay.
|
|
18
|
+
*/
|
|
19
|
+
/** The flow file format this package writes and reads. */
|
|
20
|
+
export declare const FLOW_FORMAT_VERSION = 1;
|
|
21
|
+
/** Most steps one flow holds. */
|
|
22
|
+
export declare const MAX_FLOW_STEPS = 200;
|
|
23
|
+
/** The prefix of the flows an identity records by itself (`record.flows`). */
|
|
24
|
+
export declare const AUTO_PREFIX = "auto-";
|
|
25
|
+
export declare class FlowError extends Error {
|
|
26
|
+
constructor(message: string);
|
|
27
|
+
}
|
|
28
|
+
/** One way to find an element again, as a Playwright selector. */
|
|
29
|
+
export interface FlowLocator {
|
|
30
|
+
/** `generated` (Playwright's own), `role` (role and accessible name), `text`, `css`. */
|
|
31
|
+
kind: "generated" | "role" | "text" | "css";
|
|
32
|
+
selector: string;
|
|
33
|
+
}
|
|
34
|
+
/** An element a step acts on. */
|
|
35
|
+
export interface FlowTarget {
|
|
36
|
+
/** What the element is, for people and for the failure report ("Sign in button"). */
|
|
37
|
+
description?: string;
|
|
38
|
+
/** Tried in order on replay; the first that matches exactly one visible element wins. */
|
|
39
|
+
locators: FlowLocator[];
|
|
40
|
+
/** The snapshot ref the element had when it was recorded; never used to replay. */
|
|
41
|
+
ref?: string;
|
|
42
|
+
}
|
|
43
|
+
/** A parameter slot inside a step's arguments. */
|
|
44
|
+
export interface ParamRef {
|
|
45
|
+
$param: string;
|
|
46
|
+
}
|
|
47
|
+
export interface FlowParam {
|
|
48
|
+
name: string;
|
|
49
|
+
/** True: the value is never stored, and replay needs it (`keychain:<item>` keeps it from the model). */
|
|
50
|
+
sensitive: boolean;
|
|
51
|
+
/** What was typed when it was recorded; never present for a sensitive parameter. */
|
|
52
|
+
default?: string;
|
|
53
|
+
/** The field it was typed into. */
|
|
54
|
+
description?: string;
|
|
55
|
+
}
|
|
56
|
+
export interface FlowStep {
|
|
57
|
+
tool: string;
|
|
58
|
+
/** The tool's arguments without its element targets; parameter slots are `ParamRef`s. */
|
|
59
|
+
args: Record<string, unknown>;
|
|
60
|
+
/** The element of each target argument, by its path in `args` (`target`, `fields.0.target`). */
|
|
61
|
+
targets?: Record<string, FlowTarget>;
|
|
62
|
+
/** The URL of the page when the step ran (no query or fragment). */
|
|
63
|
+
url?: string;
|
|
64
|
+
}
|
|
65
|
+
export interface Flow {
|
|
66
|
+
version: number;
|
|
67
|
+
name: string;
|
|
68
|
+
description?: string;
|
|
69
|
+
identity: string;
|
|
70
|
+
created: string;
|
|
71
|
+
updated: string;
|
|
72
|
+
params: FlowParam[];
|
|
73
|
+
steps: FlowStep[];
|
|
74
|
+
}
|
|
75
|
+
export interface FlowSummary {
|
|
76
|
+
name: string;
|
|
77
|
+
description?: string;
|
|
78
|
+
steps: number;
|
|
79
|
+
params: {
|
|
80
|
+
name: string;
|
|
81
|
+
sensitive: boolean;
|
|
82
|
+
hasDefault: boolean;
|
|
83
|
+
}[];
|
|
84
|
+
/** First page the flow visits, when it navigates. */
|
|
85
|
+
start?: string;
|
|
86
|
+
auto: boolean;
|
|
87
|
+
updated: string;
|
|
88
|
+
file: string;
|
|
89
|
+
}
|
|
90
|
+
export declare function assertFlowName(name: string): void;
|
|
91
|
+
/** Where an identity's flows live: `<data>/browser/flows/<id>`. */
|
|
92
|
+
export declare function flowsDir(id: string, env?: NodeJS.ProcessEnv): string;
|
|
93
|
+
export declare function flowPath(id: string, name: string, env?: NodeJS.ProcessEnv): string;
|
|
94
|
+
/** Everything wrong with a parsed flow file; empty when it is valid. */
|
|
95
|
+
export declare function flowProblems(raw: unknown): string[];
|
|
96
|
+
/** The parameter names a value uses, at any depth. */
|
|
97
|
+
export declare function paramRefs(value: unknown): string[];
|
|
98
|
+
/** A copy of `value` with every parameter slot replaced by its value. */
|
|
99
|
+
export declare function fillParams(value: unknown, values: Record<string, string>): unknown;
|
|
100
|
+
/** Reads `a.b.0.c` of an object. */
|
|
101
|
+
export declare function getPath(obj: unknown, path: string): unknown;
|
|
102
|
+
/** Sets `a.b.0.c` of an object that already has every level but the last. */
|
|
103
|
+
export declare function setPath(obj: Record<string, unknown>, path: string, value: unknown): void;
|
|
104
|
+
/**
|
|
105
|
+
* The parameter values a replay runs with: the given ones, then the defaults. `missing` lists
|
|
106
|
+
* the parameters with neither (every sensitive one not given), `unknown` the given names the
|
|
107
|
+
* flow does not have.
|
|
108
|
+
*/
|
|
109
|
+
export declare function resolveParams(flow: Pick<Flow, "params">, given?: Record<string, string>): {
|
|
110
|
+
values: Record<string, string>;
|
|
111
|
+
missing: FlowParam[];
|
|
112
|
+
unknown: string[];
|
|
113
|
+
};
|
|
114
|
+
/** A step in a few words: `browser_click "Sign in" button`, `browser_navigate https://...`. */
|
|
115
|
+
export declare function describeStep(step: FlowStep): string;
|
|
116
|
+
/** Writes a flow (mode 600, through a rename). Validates first. */
|
|
117
|
+
export declare function writeFlow(id: string, flow: Flow, env?: NodeJS.ProcessEnv): string;
|
|
118
|
+
/** A saved flow; throws a FlowError when there is none or it cannot be used. */
|
|
119
|
+
export declare function readFlow(id: string, name: string, env?: NodeJS.ProcessEnv): Flow;
|
|
120
|
+
/** The identity's saved flows, newest first. Files that cannot be read are left out. */
|
|
121
|
+
export declare function listFlows(id: string, env?: NodeJS.ProcessEnv): FlowSummary[];
|
|
122
|
+
/** Deletes a flow; false when there was none. */
|
|
123
|
+
export declare function removeFlow(id: string, name: string, env?: NodeJS.ProcessEnv): boolean;
|
|
124
|
+
/** Keeps the newest `keep` flows the identity recorded by itself; returns how many went. */
|
|
125
|
+
export declare function rotateAutoFlows(id: string, keep: number, env?: NodeJS.ProcessEnv): number;
|
|
126
|
+
/** Removes every flow of an identity (when the identity goes). */
|
|
127
|
+
export declare function removeFlows(id: string, env?: NodeJS.ProcessEnv): void;
|