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/api.d.ts ADDED
@@ -0,0 +1,96 @@
1
+ import { engineId, formatBenchTable, runBench } from "./bench.js";
2
+ import { runDoctor } from "./doctor.js";
3
+ import { readHealth } from "./health.js";
4
+ import { addIdentity, identityExists, inUseBy, isInUse, listIdentities, removeIdentity } from "./identities.js";
5
+ import { assertIdentityId, identityDir } from "./ids.js";
6
+ import { loginIdentity } from "./login.js";
7
+ import { reputationReport } from "./reputation.js";
8
+ import { exportSession, importSession, readSessionExport } from "./session-export.js";
9
+ import { flowsDir, listFlows, readFlow, removeFlow } from "./flows.js";
10
+ import { listRecordings, openTraceViewer, recordingsDir, traceViewerCommand } from "./recordings.js";
11
+ import { replayFlow } from "./replay.js";
12
+ import { liveLink, livePause, liveResume, liveStatus } from "./live-client.js";
13
+ import { parseTotpSecret } from "./totp.js";
14
+ import { vaultAdd, vaultClear, vaultList, vaultRemove, vaultSetSubmit } from "./vault.js";
15
+ import { checkIdentitySettings, identitySettingsPath, writeIdentitySettings } from "./settings.js";
16
+ import { manifestSnippet } from "./snippet.js";
17
+ /**
18
+ * The contract between turno-browser and turno-cli. turno-cli installs this package
19
+ * apart, types it with `import type` (erased at build, so the package stays optional) and,
20
+ * when it loads it, compares `API_VERSION` with the version it was built against:
21
+ *
22
+ * - `minor` goes up when a member is added; a CLI that needs the new member refuses an older
23
+ * package with one message that says to update it.
24
+ * - `major` goes up when a member is removed or renamed, or its arguments, result or meaning
25
+ * change; an older CLI then refuses this package and says to update turno.
26
+ *
27
+ * `test/api.test.ts` lists the members, so a change here cannot ship without the version.
28
+ */
29
+ export declare const API_VERSION: Readonly<{
30
+ readonly major: 1;
31
+ readonly minor: 10;
32
+ }>;
33
+ /** What `API_VERSION` looks like to a reader that does not know this package's version. */
34
+ export interface ApiVersion {
35
+ readonly major: number;
36
+ readonly minor: number;
37
+ }
38
+ /**
39
+ * The functions turno-cli calls: identities, their settings, login, doctor, reputation, bench
40
+ * (1.1) the credential vault, (1.2) session export and import, (1.3) the `humanize` key of
41
+ * identity.json (no new member: `writeIdentitySettings` accepts it, an older package refuses it)
42
+ * (1.4) the `sharing` key of identity.json and `manifestSnippet(id, { sharing })`, (1.5) the
43
+ * `engine` and `attach` keys of identity.json and the engine checks of `runDoctor`, (1.6) the
44
+ * `record` key of identity.json, saved flows, replay and recordings, (1.7) the `act` and
45
+ * `captcha` keys of identity.json (no new member) and `solved` in each site of
46
+ * `reputationReport`, (1.8) the `tabLocks` key of identity.json and
47
+ * `runDoctor({ servers })`, the mcp.toml servers of each identity, (1.9) the `live` key of
48
+ * identity.json and the live view of a running server (status, pause, resume, a one-time link),
49
+ * and (1.10) the `userAgent` and `proxy` keys and the `"camoufox"` engine of identity.json, and
50
+ * the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them).
51
+ */
52
+ export declare const api: Readonly<{
53
+ ENGINES: readonly ["chrome-headed", "chrome-headless", "chrome-baseline", "firefox"];
54
+ engineId: typeof engineId;
55
+ listIdentities: typeof listIdentities;
56
+ addIdentity: typeof addIdentity;
57
+ removeIdentity: typeof removeIdentity;
58
+ identityExists: typeof identityExists;
59
+ identityDir: typeof identityDir;
60
+ identitySettingsPath: typeof identitySettingsPath;
61
+ isInUse: typeof isInUse;
62
+ inUseBy: typeof inUseBy;
63
+ assertIdentityId: typeof assertIdentityId;
64
+ manifestSnippet: typeof manifestSnippet;
65
+ loginIdentity: typeof loginIdentity;
66
+ checkIdentitySettings: typeof checkIdentitySettings;
67
+ writeIdentitySettings: typeof writeIdentitySettings;
68
+ readHealth: typeof readHealth;
69
+ runDoctor: typeof runDoctor;
70
+ reputationReport: typeof reputationReport;
71
+ runBench: typeof runBench;
72
+ formatBenchTable: typeof formatBenchTable;
73
+ vaultAdd: typeof vaultAdd;
74
+ vaultList: typeof vaultList;
75
+ vaultRemove: typeof vaultRemove;
76
+ vaultClear: typeof vaultClear;
77
+ vaultSetSubmit: typeof vaultSetSubmit;
78
+ parseTotpSecret: typeof parseTotpSecret;
79
+ exportSession: typeof exportSession;
80
+ readSessionExport: typeof readSessionExport;
81
+ importSession: typeof importSession;
82
+ flowsDir: typeof flowsDir;
83
+ listFlows: typeof listFlows;
84
+ readFlow: typeof readFlow;
85
+ removeFlow: typeof removeFlow;
86
+ replayFlow: typeof replayFlow;
87
+ listRecordings: typeof listRecordings;
88
+ recordingsDir: typeof recordingsDir;
89
+ traceViewerCommand: typeof traceViewerCommand;
90
+ openTraceViewer: typeof openTraceViewer;
91
+ liveStatus: typeof liveStatus;
92
+ livePause: typeof livePause;
93
+ liveResume: typeof liveResume;
94
+ liveLink: typeof liveLink;
95
+ }>;
96
+ export type BrowserApi = typeof api;
package/dist/api.js ADDED
@@ -0,0 +1,88 @@
1
+ import { ENGINES, engineId, formatBenchTable, runBench } from "./bench.js";
2
+ import { runDoctor } from "./doctor.js";
3
+ import { readHealth } from "./health.js";
4
+ import { addIdentity, identityExists, inUseBy, isInUse, listIdentities, removeIdentity } from "./identities.js";
5
+ import { assertIdentityId, identityDir } from "./ids.js";
6
+ import { loginIdentity } from "./login.js";
7
+ import { reputationReport } from "./reputation.js";
8
+ import { exportSession, importSession, readSessionExport } from "./session-export.js";
9
+ import { flowsDir, listFlows, readFlow, removeFlow } from "./flows.js";
10
+ import { listRecordings, openTraceViewer, recordingsDir, traceViewerCommand } from "./recordings.js";
11
+ import { replayFlow } from "./replay.js";
12
+ import { liveLink, livePause, liveResume, liveStatus } from "./live-client.js";
13
+ import { parseTotpSecret } from "./totp.js";
14
+ import { vaultAdd, vaultClear, vaultList, vaultRemove, vaultSetSubmit } from "./vault.js";
15
+ import { checkIdentitySettings, identitySettingsPath, writeIdentitySettings } from "./settings.js";
16
+ import { manifestSnippet } from "./snippet.js";
17
+ /**
18
+ * The contract between turno-browser and turno-cli. turno-cli installs this package
19
+ * apart, types it with `import type` (erased at build, so the package stays optional) and,
20
+ * when it loads it, compares `API_VERSION` with the version it was built against:
21
+ *
22
+ * - `minor` goes up when a member is added; a CLI that needs the new member refuses an older
23
+ * package with one message that says to update it.
24
+ * - `major` goes up when a member is removed or renamed, or its arguments, result or meaning
25
+ * change; an older CLI then refuses this package and says to update turno.
26
+ *
27
+ * `test/api.test.ts` lists the members, so a change here cannot ship without the version.
28
+ */
29
+ export const API_VERSION = Object.freeze({ major: 1, minor: 10 });
30
+ /**
31
+ * The functions turno-cli calls: identities, their settings, login, doctor, reputation, bench
32
+ * (1.1) the credential vault, (1.2) session export and import, (1.3) the `humanize` key of
33
+ * identity.json (no new member: `writeIdentitySettings` accepts it, an older package refuses it)
34
+ * (1.4) the `sharing` key of identity.json and `manifestSnippet(id, { sharing })`, (1.5) the
35
+ * `engine` and `attach` keys of identity.json and the engine checks of `runDoctor`, (1.6) the
36
+ * `record` key of identity.json, saved flows, replay and recordings, (1.7) the `act` and
37
+ * `captcha` keys of identity.json (no new member) and `solved` in each site of
38
+ * `reputationReport`, (1.8) the `tabLocks` key of identity.json and
39
+ * `runDoctor({ servers })`, the mcp.toml servers of each identity, (1.9) the `live` key of
40
+ * identity.json and the live view of a running server (status, pause, resume, a one-time link),
41
+ * and (1.10) the `userAgent` and `proxy` keys and the `"camoufox"` engine of identity.json, and
42
+ * the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them).
43
+ */
44
+ export const api = Object.freeze({
45
+ ENGINES,
46
+ engineId,
47
+ listIdentities,
48
+ addIdentity,
49
+ removeIdentity,
50
+ identityExists,
51
+ identityDir,
52
+ identitySettingsPath,
53
+ isInUse,
54
+ inUseBy,
55
+ assertIdentityId,
56
+ manifestSnippet,
57
+ loginIdentity,
58
+ checkIdentitySettings,
59
+ writeIdentitySettings,
60
+ readHealth,
61
+ runDoctor,
62
+ reputationReport,
63
+ runBench,
64
+ formatBenchTable,
65
+ vaultAdd,
66
+ vaultList,
67
+ vaultRemove,
68
+ vaultClear,
69
+ vaultSetSubmit,
70
+ parseTotpSecret,
71
+ exportSession,
72
+ readSessionExport,
73
+ importSession,
74
+ flowsDir,
75
+ listFlows,
76
+ readFlow,
77
+ removeFlow,
78
+ replayFlow,
79
+ listRecordings,
80
+ recordingsDir,
81
+ traceViewerCommand,
82
+ openTraceViewer,
83
+ liveStatus,
84
+ livePause,
85
+ liveResume,
86
+ liveLink,
87
+ });
88
+ //# sourceMappingURL=api.js.map
package/dist/argv.d.ts CHANGED
@@ -1,19 +1,30 @@
1
+ import type { EngineFlags } from "./engine.js";
2
+ import type { LiveFlags } from "./live.js";
3
+ import type { TuningFlags } from "./tuning.js";
1
4
  /**
2
5
  * Turns `turno-browser-mcp [--identity <id>] [playwright-mcp flags]` into the argv for the
3
- * Patchright MCP program, adding the defaults of ADR 0005 that the user did not set:
6
+ * Patchright MCP program, adding turno's defaults that the user did not set:
4
7
  *
5
8
  * - `--browser chrome`: the installed Google Chrome, not a bundled Chromium.
6
9
  * - `--user-data-dir <dir>`: the identity's persistent profile, or a fresh temporary one.
7
10
  * Patchright recommends persistent contexts, and the upstream default (a profile shared by
8
11
  * every server started in the same folder) is neither isolated nor per identity.
9
12
  *
13
+ * - `--config <file>`: a generated Playwright MCP config whose `timeouts.idle` closes Chrome
14
+ * after `TURNO_BROWSER_IDLE` (default 15 minutes) without a tool call, headed included; the
15
+ * next call opens it again with the same profile. `--idle-timeout` and
16
+ * `PLAYWRIGHT_MCP_IDLE_TIMEOUT` still win, and a `--config` of the user's own replaces it.
17
+ *
10
18
  * Headed mode and `viewport: null` are already the program's defaults for headed runs, so
11
19
  * nothing is added for them; no init scripts are ever added.
12
20
  *
21
+ * The tab governor, background throttling, humanize and sharing flags (`TUNING_FLAGS`) are turno's: they are
22
+ * taken out here and win over identity.json. So are `--engine <chrome|lightpanda|camoufox>` and `--attach <target>` (`engine.ts`); with either and
23
+ * no identity there is no Chrome profile to create. So are `--live` and `--live-wait <duration>` (`live.ts`), which need an identity.
24
+ *
13
25
  * An identity holds saved logins, so serving it over HTTP (`--port`, `--host`) lets any local
14
26
  * process drive a signed-in browser without the stdio pipe or mcpd's token. That needs
15
- * `--allow-http-identity`, and even then the server binds to 127.0.0.1 and keeps the Host check
16
- * (ADR 0019).
27
+ * `--allow-http-identity`, and even then the server binds to 127.0.0.1 and keeps the Host check.
17
28
  */
18
29
  export interface BuiltArgv {
19
30
  /** Arguments for the MCP program (without node and script path). */
@@ -23,12 +34,53 @@ export interface BuiltArgv {
23
34
  userDataDir?: string;
24
35
  /** Temporary dir to delete on exit (only for runs without an identity). */
25
36
  tempDir?: string;
37
+ /** The Playwright MCP config to write before the program starts, when turno passes one. */
38
+ config?: {
39
+ path: string;
40
+ data: PlaywrightMcpConfig;
41
+ };
42
+ /** turno's own flags for the host, when any was given. */
43
+ tuning?: TuningFlags;
44
+ /** `--engine` and `--attach`, when given. */
45
+ engineFlags?: EngineFlags;
46
+ /** `--live` and `--live-wait`, when given. */
47
+ live?: LiveFlags;
26
48
  }
49
+ /** The keys of the Playwright MCP config file that turno sets (pinned by the contract test). */
50
+ export interface PlaywrightMcpConfig {
51
+ timeouts: {
52
+ idle: number;
53
+ };
54
+ }
55
+ /** How long Chrome stays open without a tool call, unless TURNO_BROWSER_IDLE says otherwise. */
56
+ export declare const DEFAULT_BROWSER_IDLE_MS: number;
57
+ /** `"15m"`, `"90s"`, `"500ms"`, `"1h"` or `"0"` (never) in milliseconds. */
58
+ export declare function parseIdle(value: string): number;
27
59
  export interface BuildOptions {
28
60
  env?: NodeJS.ProcessEnv;
29
61
  /** Creates the temporary profile root. Injected by tests. */
30
62
  makeTempDir?: () => string;
31
63
  }
64
+ /** turno's flags for the tab governor and background throttling, with what each takes. */
65
+ export declare const TUNING_FLAGS: {
66
+ readonly "--max-tabs": "<n>";
67
+ readonly "--popups": "<close|keep>";
68
+ readonly "--park-after": "<duration>";
69
+ readonly "--close-after": "<duration>";
70
+ readonly "--background-throttling": "";
71
+ readonly "--humanize": "<off|light|full|adaptive>";
72
+ readonly "--sharing": "<session|tabs>";
73
+ };
74
+ /** Removes turno's tuning flags (`TUNING_FLAGS`) from args and returns their values. */
75
+ export declare function extractTuning(args: string[]): {
76
+ tuning?: TuningFlags;
77
+ rest: string[];
78
+ };
79
+ /** Removes `--engine` and `--attach` from args and returns their values, checked. */
80
+ export declare function extractEngine(args: string[]): {
81
+ engineFlags?: EngineFlags;
82
+ rest: string[];
83
+ };
32
84
  /** Removes `--identity <id>` / `--identity=<id>` from args and returns the id. */
33
85
  export declare function extractIdentity(args: string[]): {
34
86
  identity?: string;
package/dist/argv.js CHANGED
@@ -1,7 +1,24 @@
1
1
  import { mkdtempSync } from "node:fs";
2
2
  import { tmpdir } from "node:os";
3
3
  import { join } from "node:path";
4
+ import { browserPaths as paths } from "turno-core/paths";
5
+ import { HUMANIZE_LEVELS } from "./humanize.js";
4
6
  import { assertIdentityId, identityDir } from "./identities.js";
7
+ import { MAX_LIVE_WAIT_MS, MIN_LIVE_WAIT_MS } from "./settings.js";
8
+ import { parseAttachTarget } from "./engine-attach.js";
9
+ import { parseDuration } from "./units.js";
10
+ /** How long Chrome stays open without a tool call, unless TURNO_BROWSER_IDLE says otherwise. */
11
+ export const DEFAULT_BROWSER_IDLE_MS = 15 * 60_000;
12
+ const UNITS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
13
+ /** `"15m"`, `"90s"`, `"500ms"`, `"1h"` or `"0"` (never) in milliseconds. */
14
+ export function parseIdle(value) {
15
+ if (value.trim() === "0")
16
+ return 0;
17
+ const m = /^(\d+)(ms|s|m|h)$/.exec(value.trim());
18
+ if (!m)
19
+ throw new Error(`TURNO_BROWSER_IDLE must be a duration like "15m", "90s" or "0" (never), not "${value}"`);
20
+ return Number(m[1]) * UNITS[m[2]];
21
+ }
5
22
  /** Flags that point the program at a browser it does not launch itself. */
6
23
  const EXTERNAL_BROWSER = ["--cdp-endpoint", "--endpoint", "--extension"];
7
24
  /** Opt-in to serve an identity over HTTP; consumed here, never passed on. */
@@ -48,6 +65,144 @@ function hasFlag(args, flag) {
48
65
  function hasAny(args, flags) {
49
66
  return flags.some((f) => hasFlag(args, f));
50
67
  }
68
+ /** turno's flags for the tab governor and background throttling, with what each takes. */
69
+ export const TUNING_FLAGS = {
70
+ "--max-tabs": "<n>",
71
+ "--popups": "<close|keep>",
72
+ "--park-after": "<duration>",
73
+ "--close-after": "<duration>",
74
+ "--background-throttling": "",
75
+ "--humanize": "<off|light|full|adaptive>",
76
+ "--sharing": "<session|tabs>",
77
+ };
78
+ function tuningValue(flag, value, out) {
79
+ if (flag === "--max-tabs") {
80
+ if (!/^\d+$/.test(value) || Number(value) > 100)
81
+ throw new Error(`--max-tabs must be a whole number from 0 (no cap) to 100, not "${value}"`);
82
+ out.maxTabs = Number(value);
83
+ }
84
+ else if (flag === "--humanize") {
85
+ if (!HUMANIZE_LEVELS.includes(value))
86
+ throw new Error(`--humanize must be ${HUMANIZE_LEVELS.join(", ")}, not "${value}"`);
87
+ out.humanize = value;
88
+ }
89
+ else if (flag === "--popups") {
90
+ if (value !== "close" && value !== "keep")
91
+ throw new Error(`--popups must be "close" or "keep", not "${value}"`);
92
+ out.popups = value;
93
+ }
94
+ else if (flag === "--sharing") {
95
+ if (value !== "session" && value !== "tabs")
96
+ throw new Error(`--sharing must be "session" (one agent session at a time) or "tabs", not "${value}"`);
97
+ out.sharing = value;
98
+ }
99
+ else {
100
+ const ms = parseDuration(value);
101
+ if (ms === undefined)
102
+ throw new Error(`${flag} must be a duration like "5m", "90s" or "0" (off), not "${value}"`);
103
+ if (flag === "--park-after")
104
+ out.parkAfterMs = ms;
105
+ else
106
+ out.closeAfterMs = ms;
107
+ }
108
+ }
109
+ /** Removes turno's tuning flags (`TUNING_FLAGS`) from args and returns their values. */
110
+ export function extractTuning(args) {
111
+ const rest = [];
112
+ const out = {};
113
+ let any = false;
114
+ for (let i = 0; i < args.length; i++) {
115
+ const a = args[i];
116
+ const eq = a.indexOf("=");
117
+ const name = (eq > 0 ? a.slice(0, eq) : a);
118
+ if (!Object.hasOwn(TUNING_FLAGS, name)) {
119
+ rest.push(a);
120
+ continue;
121
+ }
122
+ any = true;
123
+ if (name === "--background-throttling") {
124
+ if (eq > 0)
125
+ throw new Error("--background-throttling takes no value");
126
+ out.backgroundThrottling = true;
127
+ continue;
128
+ }
129
+ let value;
130
+ if (eq > 0)
131
+ value = a.slice(eq + 1);
132
+ else {
133
+ value = args[i + 1];
134
+ if (value === undefined || value.startsWith("--"))
135
+ throw new Error(`${name} needs a value ${TUNING_FLAGS[name]}`);
136
+ i++;
137
+ }
138
+ tuningValue(name, value, out);
139
+ }
140
+ return any ? { tuning: out, rest } : { rest };
141
+ }
142
+ /** The value of `--flag v` or `--flag=v` at `args[i]`, and how many items it took. */
143
+ function valueAt(args, i, flag) {
144
+ const a = args[i];
145
+ if (a.startsWith(`${flag}=`))
146
+ return { value: a.slice(flag.length + 1), used: 1 };
147
+ if (a !== flag)
148
+ return undefined;
149
+ const v = args[i + 1];
150
+ if (v === undefined || v.startsWith("--"))
151
+ throw new Error(`${flag} needs a value`);
152
+ return { value: v, used: 2 };
153
+ }
154
+ /** Removes `--engine` and `--attach` from args and returns their values, checked. */
155
+ export function extractEngine(args) {
156
+ const rest = [];
157
+ const out = {};
158
+ for (let i = 0; i < args.length; i++) {
159
+ const engine = valueAt(args, i, "--engine");
160
+ const attach = engine ? undefined : valueAt(args, i, "--attach");
161
+ if (engine) {
162
+ if (engine.value !== "chrome" && engine.value !== "lightpanda" && engine.value !== "camoufox")
163
+ throw new Error(`--engine must be "chrome", "lightpanda" (read mode) or "camoufox", not "${engine.value}"`);
164
+ out.engine = engine.value;
165
+ i += engine.used - 1;
166
+ }
167
+ else if (attach) {
168
+ const target = parseAttachTarget(attach.value);
169
+ if ("error" in target)
170
+ throw new Error(target.error.replace(/^attach/, "--attach"));
171
+ out.attach = attach.value.trim();
172
+ i += attach.used - 1;
173
+ }
174
+ else
175
+ rest.push(args[i]);
176
+ }
177
+ if ((out.engine === "lightpanda" || out.engine === "camoufox") && out.attach !== undefined)
178
+ throw new Error(`--attach and --engine ${out.engine} do not go together: pick one`);
179
+ return out.engine !== undefined || out.attach !== undefined ? { engineFlags: out, rest } : { rest };
180
+ }
181
+ /** Removes `--live` and `--live-wait <duration>` from args and returns their values, checked. */
182
+ function extractLive(args) {
183
+ const rest = [];
184
+ const out = {};
185
+ for (let i = 0; i < args.length; i++) {
186
+ const a = args[i];
187
+ if (a === "--live") {
188
+ out.live = true;
189
+ continue;
190
+ }
191
+ if (a.startsWith("--live="))
192
+ throw new Error("--live takes no value");
193
+ const wait = valueAt(args, i, "--live-wait");
194
+ if (!wait) {
195
+ rest.push(a);
196
+ continue;
197
+ }
198
+ const ms = parseDuration(wait.value);
199
+ if (ms === undefined || ms < MIN_LIVE_WAIT_MS || ms > MAX_LIVE_WAIT_MS)
200
+ throw new Error(`--live-wait must be a duration from "5s" to "30m", like "2m", not "${wait.value}"`);
201
+ out.waitMs = ms;
202
+ i += wait.used - 1;
203
+ }
204
+ return out.live !== undefined || out.waitMs !== undefined ? { live: out, rest } : { rest };
205
+ }
51
206
  /** Removes `--identity <id>` / `--identity=<id>` from args and returns the id. */
52
207
  export function extractIdentity(args) {
53
208
  const rest = [];
@@ -77,12 +232,29 @@ function defaultTempDir() {
77
232
  }
78
233
  export function buildArgv(rawArgs, options = {}) {
79
234
  const env = options.env ?? process.env;
80
- const { identity, rest } = extractIdentity(rawArgs);
235
+ const { identity, rest: afterIdentity } = extractIdentity(rawArgs);
236
+ const { tuning, rest: afterTuning } = extractTuning(afterIdentity);
237
+ const { engineFlags, rest: afterEngine } = extractEngine(afterTuning);
238
+ const { live, rest } = extractLive(afterEngine);
239
+ // The live view's control socket and live.json belong to the identity's state folder.
240
+ if (live && identity === undefined)
241
+ throw new Error("--live and --live-wait apply only with --identity");
81
242
  const allowHttp = rest.includes(ALLOW_HTTP_IDENTITY);
82
243
  const args = rest.filter((a) => a !== ALLOW_HTTP_IDENTITY);
83
244
  guardHttp(args, identity, allowHttp);
84
245
  const external = hasAny(args, EXTERNAL_BROWSER);
85
- const out = { args };
246
+ const out = {
247
+ args,
248
+ ...(tuning ? { tuning } : {}),
249
+ ...(engineFlags ? { engineFlags } : {}),
250
+ ...(live ? { live } : {}),
251
+ };
252
+ const otherEngine = engineFlags?.engine === "lightpanda" || engineFlags?.engine === "camoufox" || engineFlags?.attach !== undefined;
253
+ if (otherEngine) {
254
+ const clash = ["--isolated", "--user-data-dir", ...EXTERNAL_BROWSER].find((f) => hasFlag(args, f));
255
+ if (clash)
256
+ throw new Error(`${engineFlags?.attach !== undefined ? "--attach" : `--engine ${engineFlags?.engine}`} cannot be combined with ${clash}`);
257
+ }
86
258
  if (identity !== undefined) {
87
259
  const clash = ["--user-data-dir", "--isolated", ...EXTERNAL_BROWSER].find((f) => hasFlag(args, f));
88
260
  if (clash)
@@ -91,16 +263,24 @@ export function buildArgv(rawArgs, options = {}) {
91
263
  }
92
264
  if (!external && !hasFlag(args, "--browser"))
93
265
  args.push("--browser", "chrome");
94
- if (!external && !hasFlag(args, "--user-data-dir") && !hasFlag(args, "--isolated")) {
95
- if (identity !== undefined) {
96
- out.userDataDir = identityDir(identity, env);
97
- }
98
- else {
99
- out.tempDir = (options.makeTempDir ?? defaultTempDir)();
100
- out.userDataDir = join(out.tempDir, "profile");
101
- }
266
+ const makeTemp = () => {
267
+ out.tempDir ??= (options.makeTempDir ?? defaultTempDir)();
268
+ return out.tempDir;
269
+ };
270
+ // Read mode, Camoufox and attach mode without an identity start no Chrome, so they need no profile.
271
+ const needsProfile = !(otherEngine && identity === undefined);
272
+ if (!external && needsProfile && !hasFlag(args, "--user-data-dir") && !hasFlag(args, "--isolated")) {
273
+ out.userDataDir = identity !== undefined ? identityDir(identity, env) : join(makeTemp(), "profile");
102
274
  args.push("--user-data-dir", out.userDataDir);
103
275
  }
276
+ if (!external && !hasFlag(args, "--config") && !env.PLAYWRIGHT_MCP_CONFIG) {
277
+ const idle = env.TURNO_BROWSER_IDLE !== undefined ? parseIdle(env.TURNO_BROWSER_IDLE) : DEFAULT_BROWSER_IDLE_MS;
278
+ const path = identity !== undefined
279
+ ? join(paths(env).identityStateDir, identity, "mcp-config.json")
280
+ : join(makeTemp(), "mcp-config.json");
281
+ out.config = { path, data: { timeouts: { idle } } };
282
+ args.push("--config", path);
283
+ }
104
284
  return out;
105
285
  }
106
286
  //# sourceMappingURL=argv.js.map
@@ -0,0 +1,19 @@
1
+ import type { TurnoTool } from "./tools.js";
2
+ import { type ToolResult } from "./upstream.js";
3
+ /**
4
+ * `browser_batch`: several stock actions in one tool call. Each action runs through
5
+ * the same path as a call of its own (the tab governor, the click diagnosis), but without the
6
+ * page snapshot a stock action adds to its result; the batch returns one line per action and,
7
+ * when asked, one snapshot after the last. It stops at the first action that fails.
8
+ *
9
+ * It saves the model a round trip per action and the server an accessibility snapshot per
10
+ * action (`bench/browser-roundtrips.mjs` measures both).
11
+ */
12
+ /** Most actions in one batch. */
13
+ export declare const MAX_BATCH = 20;
14
+ /** The sections of an upstream result text (`### Title` then the body). */
15
+ export declare function sections(text: string): Map<string, string>;
16
+ export declare function clip(text: string, max?: number): string;
17
+ export declare function textOf(result: ToolResult): string;
18
+ /** The tool. Its schema is built on first use, so importing the registry does not load the bundle. */
19
+ export declare function batchTool(): TurnoTool;