turno-browser 0.3.0 → 0.5.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 (131) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +95 -123
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +117 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +600 -0
  7. package/dist/api.d.ts +90 -2
  8. package/dist/api.js +41 -4
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/background-state.d.ts +54 -0
  12. package/dist/background-state.js +97 -0
  13. package/dist/background.d.ts +69 -0
  14. package/dist/background.js +458 -0
  15. package/dist/batch.d.ts +5 -0
  16. package/dist/batch.js +3 -3
  17. package/dist/bin/mcp.js +103 -6
  18. package/dist/captcha.d.ts +77 -0
  19. package/dist/captcha.js +334 -0
  20. package/dist/cdp-relay.d.ts +20 -0
  21. package/dist/cdp-relay.js +101 -0
  22. package/dist/chrome-features.d.ts +23 -0
  23. package/dist/chrome-features.js +44 -0
  24. package/dist/cli/background.d.ts +11 -0
  25. package/dist/cli/background.js +132 -0
  26. package/dist/cli/commands.d.ts +16 -0
  27. package/dist/cli/commands.js +515 -0
  28. package/dist/cli/context.d.ts +75 -0
  29. package/dist/cli/context.js +44 -0
  30. package/dist/cli/do-background.d.ts +27 -0
  31. package/dist/cli/do-background.js +212 -0
  32. package/dist/cli/do.d.ts +85 -0
  33. package/dist/cli/do.js +558 -0
  34. package/dist/cli/flows.d.ts +28 -0
  35. package/dist/cli/flows.js +303 -0
  36. package/dist/cli/identity.d.ts +37 -0
  37. package/dist/cli/identity.js +906 -0
  38. package/dist/cli/live.d.ts +7 -0
  39. package/dist/cli/live.js +99 -0
  40. package/dist/cli/main.d.ts +16 -0
  41. package/dist/cli/main.js +171 -0
  42. package/dist/cli/secret.d.ts +4 -0
  43. package/dist/cli/secret.js +151 -0
  44. package/dist/cli/session.d.ts +6 -0
  45. package/dist/cli/session.js +106 -0
  46. package/dist/cli/setup.d.ts +7 -0
  47. package/dist/cli/setup.js +180 -0
  48. package/dist/cli/vault.d.ts +5 -0
  49. package/dist/cli/vault.js +192 -0
  50. package/dist/client.d.ts +82 -0
  51. package/dist/client.js +303 -0
  52. package/dist/diagnose.d.ts +7 -0
  53. package/dist/diagnose.js +61 -6
  54. package/dist/doctor.d.ts +37 -3
  55. package/dist/doctor.js +264 -6
  56. package/dist/engine-attach.d.ts +27 -0
  57. package/dist/engine-attach.js +165 -0
  58. package/dist/engine-camoufox.d.ts +32 -0
  59. package/dist/engine-camoufox.js +271 -0
  60. package/dist/engine-lightpanda.d.ts +72 -0
  61. package/dist/engine-lightpanda.js +293 -0
  62. package/dist/engine.d.ts +63 -11
  63. package/dist/engine.js +106 -29
  64. package/dist/flows.d.ts +127 -0
  65. package/dist/flows.js +294 -0
  66. package/dist/governor.d.ts +42 -7
  67. package/dist/governor.js +82 -32
  68. package/dist/health.js +2 -1
  69. package/dist/host.d.ts +38 -2
  70. package/dist/host.js +689 -52
  71. package/dist/human-input.d.ts +84 -0
  72. package/dist/human-input.js +448 -0
  73. package/dist/humanize.d.ts +123 -0
  74. package/dist/humanize.js +241 -0
  75. package/dist/identities.js +4 -1
  76. package/dist/idle-timer.d.ts +12 -0
  77. package/dist/idle-timer.js +25 -0
  78. package/dist/index.d.ts +13 -4
  79. package/dist/index.js +7 -1
  80. package/dist/lifecycle.d.ts +11 -1
  81. package/dist/lifecycle.js +11 -2
  82. package/dist/live-client.d.ts +22 -0
  83. package/dist/live-client.js +95 -0
  84. package/dist/live-page.d.ts +4 -0
  85. package/dist/live-page.js +144 -0
  86. package/dist/live-server.d.ts +173 -0
  87. package/dist/live-server.js +643 -0
  88. package/dist/live.d.ts +120 -0
  89. package/dist/live.js +204 -0
  90. package/dist/login-tool.d.ts +13 -0
  91. package/dist/login-tool.js +8 -3
  92. package/dist/login.d.ts +4 -1
  93. package/dist/login.js +12 -2
  94. package/dist/names.d.ts +28 -0
  95. package/dist/names.js +25 -0
  96. package/dist/network-chrome.d.ts +74 -0
  97. package/dist/network-chrome.js +178 -0
  98. package/dist/network.d.ts +125 -0
  99. package/dist/network.js +264 -0
  100. package/dist/opt-in-settings.d.ts +69 -0
  101. package/dist/opt-in-settings.js +152 -0
  102. package/dist/recorder.d.ts +88 -0
  103. package/dist/recorder.js +538 -0
  104. package/dist/recordings.d.ts +116 -0
  105. package/dist/recordings.js +474 -0
  106. package/dist/redact.d.ts +7 -0
  107. package/dist/redact.js +18 -0
  108. package/dist/replay.d.ts +20 -0
  109. package/dist/replay.js +383 -0
  110. package/dist/reputation.d.ts +24 -2
  111. package/dist/reputation.js +63 -17
  112. package/dist/runtime-lock.js +3 -2
  113. package/dist/session-export.js +1 -1
  114. package/dist/session.d.ts +10 -2
  115. package/dist/session.js +10 -2
  116. package/dist/settings.d.ts +104 -2
  117. package/dist/settings.js +204 -6
  118. package/dist/sharing.d.ts +96 -0
  119. package/dist/sharing.js +269 -0
  120. package/dist/snippet.d.ts +8 -2
  121. package/dist/snippet.js +10 -4
  122. package/dist/tab-locks.d.ts +63 -0
  123. package/dist/tab-locks.js +179 -0
  124. package/dist/tools.d.ts +38 -0
  125. package/dist/tools.js +20 -1
  126. package/dist/tuning.d.ts +14 -0
  127. package/dist/tuning.js +9 -0
  128. package/dist/upstream.d.ts +11 -0
  129. package/dist/vault.js +5 -4
  130. package/npm-shrinkwrap.json +6 -5
  131. package/package.json +13 -7
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
- * Another engine (another browser, an attach mode) is one more `Engine` here; the host only
17
- * sees `LaunchedBrowser`.
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,17 @@
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
- }
14
+ import { names } from "./names.js";
27
15
  /** True when the config asks for the browser the `chrome` engine launches. */
28
16
  export function usesChromeEngine(config) {
29
17
  const b = config.browser;
@@ -75,7 +63,7 @@ function profileInUse(identity, userDataDir) {
75
63
  const chrome = findProfileChrome(userDataDir);
76
64
  const who = chrome ? `a Chrome that turno-browser-mcp did not start (pid ${chrome.pid})` : "another Chrome";
77
65
  return new Error(`browser identity "${identity.id}" is in use by ${who}: a Chrome opened by hand on this profile, or a login from an older turno. ` +
78
- `Close it, then try again; \`turno browser doctor\` shows who holds each identity.`);
66
+ `Close it, then try again; \`${names().browser} doctor\` shows who holds each identity.`);
79
67
  }
80
68
  /**
81
69
  * The installed Chrome on a persistent profile, launched by turno with the options upstream's
@@ -87,17 +75,21 @@ function profileInUse(identity, userDataDir) {
87
75
  * records Chrome's PID and process group in it, gives it back when Chrome closes, and applies
88
76
  * identity.json: languages and locale as Chrome flags, the time zone as `timezoneId`. With
89
77
  * `backgroundThrottling` it drops Playwright's three anti-throttling switches and
90
- * turns off its focus emulation (`launchTuning`).
78
+ * turns off its focus emulation (`launchTuning`). Third-party storage partitioning, which
79
+ * Playwright turns off, stays on (`chrome-features.ts`).
91
80
  */
92
81
  const chromeEngine = {
93
82
  id: "chrome",
94
- async launch({ config, clientInfo, title, identity, tuning }) {
83
+ async launch({ config, clientInfo, title, identity, tuning, secret }) {
95
84
  const userDataDir = config.browser.userDataDir;
96
85
  if (userDataDir === undefined)
97
86
  throw new Error("the chrome engine needs a profile directory");
98
87
  const { tools } = upstream();
99
88
  const tracesDir = resolve(tools.outputDir({ config, cwd: clientInfo.cwd }), "traces");
100
89
  const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
90
+ // Proxy credentials and the coherent user agent are settled before the lock: a missing
91
+ // secret or an unknown Chrome version stops here, with nothing to undo.
92
+ const network = settings ? await chromeNetwork(settings, config, identity.env, secret ?? (() => { })) : undefined;
101
93
  const held = identity ? acquireRuntimeLock(identity.id, identity.env, { holder: "mcp" }) : undefined;
102
94
  let context;
103
95
  let browser;
@@ -108,19 +100,23 @@ const chromeEngine = {
108
100
  const userArgs = config.browser.launchOptions.args ?? [];
109
101
  const applied = launchSettings(settings, userArgs, systemTimezone(), config.browser.contextOptions);
110
102
  const tuned = tuning ? launchTuning(tuning) : { ignoreDefaultArgs: [], contextOptions: {} };
103
+ // Chrome's third-party storage partitioning stays on, as in a person's Chrome (`chrome-features.ts`).
104
+ const partitioning = config.browser.browserName === "chromium" && ignore !== true ? storagePartitioningArgs() : undefined;
111
105
  const launchOptions = {
112
106
  tracesDir,
113
107
  ...config.browser.launchOptions,
114
108
  ...tuned.contextOptions,
115
109
  ...config.browser.contextOptions,
116
- ...(applied.args.length ? { args: [...userArgs, ...applied.args] } : {}),
110
+ args: [...(partitioning?.args ?? []), ...userArgs, ...applied.args, ...(network?.args ?? [])],
117
111
  ...(applied.timezoneId ? { timezoneId: applied.timezoneId } : {}),
112
+ ...(network?.proxy ? { proxy: network.proxy } : {}),
118
113
  handleSIGINT: false,
119
114
  handleSIGTERM: false,
120
115
  ignoreDefaultArgs: ignore === true
121
116
  ? true
122
117
  : [
123
118
  "--disable-extensions",
119
+ ...(partitioning?.ignoreDefaultArgs ?? []),
124
120
  ...tuned.ignoreDefaultArgs,
125
121
  ...(keychainArgs(settings).ignoreDefaultArgs ?? []),
126
122
  ...(Array.isArray(ignore) ? ignore : []),
@@ -134,6 +130,9 @@ const chromeEngine = {
134
130
  }
135
131
  browser = context.browser();
136
132
  try {
133
+ const pinned = network?.pin ? pinUserAgent(context, network.pin) : undefined;
134
+ if (network?.verify)
135
+ await verifyCoherence(context, browser.version(), network.verify, pinned);
137
136
  await browser.bind(title, { workspaceDir: clientInfo.cwd });
138
137
  }
139
138
  catch (err) {
@@ -146,10 +145,10 @@ const chromeEngine = {
146
145
  throw err;
147
146
  }
148
147
  let closing = false;
149
- const idleMs = config.timeouts?.idle ?? (config.browser.launchOptions.headless ? HEADLESS_IDLE_MS : undefined);
148
+ const ms = idleMs(config);
150
149
  let idleTimer;
151
- if (idleMs) {
152
- const timer = new IdleTimer(idleMs, () => {
150
+ if (ms) {
151
+ const timer = new IdleTimer(ms, () => {
153
152
  closing = true;
154
153
  void browser.close().catch(() => { });
155
154
  });
@@ -194,7 +193,7 @@ function remoteConnectOptions(config) {
194
193
  * with the session handling of upstream's MCP program (`program.ts`): sessions share one
195
194
  * browser for `--shared-browser-context` and `--isolated`, and the last one to leave closes it.
196
195
  */
197
- export function createUpstreamEngine() {
196
+ function createUpstreamEngine() {
198
197
  let shared;
199
198
  let clients = 0;
200
199
  return {
@@ -276,4 +275,82 @@ export function createUpstreamEngine() {
276
275
  export function selectEngine(config, fallback) {
277
276
  return usesChromeEngine(config) ? chromeEngine : fallback;
278
277
  }
278
+ /**
279
+ * Flags first, then identity.json. A flag of either kind replaces both keys of identity.json:
280
+ * `--engine chrome` turns an identity's attach or read mode off for that server.
281
+ */
282
+ export function engineChoice(flags, settings) {
283
+ const fromFlags = flags.engine !== undefined || flags.attach !== undefined;
284
+ const engine = fromFlags ? flags.engine : settings?.engine;
285
+ const attach = fromFlags ? flags.attach : settings?.attach;
286
+ if (attach !== undefined) {
287
+ if (engine === "lightpanda" || engine === "camoufox")
288
+ throw new Error(`attach and the ${engine} engine do not go together: pick one`);
289
+ const target = parseAttachTarget(attach);
290
+ if ("error" in target)
291
+ throw new Error(target.error);
292
+ return { kind: "attach", target };
293
+ }
294
+ if (engine === "lightpanda")
295
+ return { kind: "lightpanda" };
296
+ return engine === "camoufox" ? { kind: "camoufox" } : { kind: "default" };
297
+ }
298
+ /**
299
+ * The host's engine: at every launch it reads the identity's settings and the flags, and hands
300
+ * the launch to `lightpanda`, `attach`, or the engine the config selects.
301
+ */
302
+ /**
303
+ * Why an engine cannot run with these settings, if it cannot: attach mode keeps one agent's tabs
304
+ * apart from the user's, not several sessions apart from each other, and read mode has no
305
+ * layout for human-like input to move over.
306
+ */
307
+ export function tuningClash(engine, tuning) {
308
+ if (engine === "attach" && tuning.sharing === "tabs")
309
+ 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 "")';
310
+ if (engine === "lightpanda" && tuning.humanize.level !== "off")
311
+ 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)";
312
+ return undefined;
313
+ }
314
+ export function createEngine(config, flags = {}, fallback) {
315
+ const base = selectEngine(config, fallback ?? createUpstreamEngine());
316
+ const lightpanda = createLightpandaEngine();
317
+ const camoufox = createCamoufoxEngine();
318
+ const choose = (identity) => {
319
+ const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
320
+ const choice = engineChoice(flags, settings);
321
+ if (choice.kind === "lightpanda")
322
+ return lightpanda;
323
+ if (choice.kind === "camoufox")
324
+ return camoufox;
325
+ if (choice.kind === "attach")
326
+ return createAttachEngine(choice.target);
327
+ return base;
328
+ };
329
+ return {
330
+ id: base.id,
331
+ launch: async (request) => {
332
+ const engine = choose(request.identity);
333
+ const settings = request.identity ? readIdentitySettings(request.identity.id, request.identity.env) : undefined;
334
+ const record = settings?.record;
335
+ // A flag can pick an engine that identity.json's other keys do not go with: refused here,
336
+ // before anything starts.
337
+ const clash = (request.tuning ? tuningClash(engine.id, request.tuning) : undefined) ??
338
+ (record ? recordEngineClash(engine.id, record) : undefined) ??
339
+ (settings ? networkEngineClash(engine.id, settings) : undefined);
340
+ if (clash)
341
+ throw new Error(clash);
342
+ return await engine.launch(request);
343
+ },
344
+ refuse(tool, identity) {
345
+ let engine;
346
+ try {
347
+ engine = choose(identity);
348
+ }
349
+ catch {
350
+ return undefined; // the launch reports a bad identity.json or flag
351
+ }
352
+ return engine.refuse?.(tool, identity);
353
+ },
354
+ };
355
+ }
279
356
  //# sourceMappingURL=engine.js.map
@@ -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;