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/flows.js ADDED
@@ -0,0 +1,294 @@
1
+ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { browserPaths as paths } from "turno-core/paths";
4
+ import { assertIdentityId } from "./ids.js";
5
+ /**
6
+ * Saved flows: the browser actions a session made on an identity, stored so that
7
+ * `browser_replay` (and `turno browser replay`) can run them again without the model working
8
+ * the page out a second time. One JSON file per flow, under `<data>/browser/flows/<id>/`, next
9
+ * to the identity's other files and never inside its Chrome profile.
10
+ *
11
+ * What a flow file holds, and what it never holds:
12
+ *
13
+ * - Each step names a browser tool and its arguments. An element is kept as several
14
+ * locators (Playwright's own pick, role and accessible name, visible text, a CSS path), tried
15
+ * in that order on replay, plus the snapshot ref it had (for reading only: refs change with
16
+ * every snapshot, so replay never uses one).
17
+ * - Text typed into a field is a parameter (`{ "$param": "email" }`). A non-sensitive one keeps
18
+ * what was typed as its default; a sensitive one (a password field, a one-time code, a card
19
+ * number, a value the agent marked) keeps no value at all, so replay needs it again.
20
+ * - A vault sign-in is a `browser_login` step with the site's name only: the values stay in
21
+ * the secret store and are read again at replay.
22
+ */
23
+ /** The flow file format this package writes and reads. */
24
+ export const FLOW_FORMAT_VERSION = 1;
25
+ /** Most steps one flow holds. */
26
+ export const MAX_FLOW_STEPS = 200;
27
+ const FLOW_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
28
+ /** The prefix of the flows an identity records by itself (`record.flows`). */
29
+ export const AUTO_PREFIX = "auto-";
30
+ export class FlowError extends Error {
31
+ constructor(message) {
32
+ super(message);
33
+ this.name = "FlowError";
34
+ }
35
+ }
36
+ function isValidFlowName(name) {
37
+ return FLOW_NAME.test(name);
38
+ }
39
+ export function assertFlowName(name) {
40
+ if (!isValidFlowName(name))
41
+ throw new FlowError(`invalid flow name "${name}": use up to 64 lowercase letters, digits, "-" and "_", starting with a letter or digit`);
42
+ }
43
+ /** Where an identity's flows live: `<data>/browser/flows/<id>`. */
44
+ export function flowsDir(id, env = process.env) {
45
+ assertIdentityId(id);
46
+ return join(paths(env).browserDir, "flows", id);
47
+ }
48
+ export function flowPath(id, name, env = process.env) {
49
+ assertFlowName(name);
50
+ return join(flowsDir(id, env), `${name}.json`);
51
+ }
52
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
53
+ function isParamRef(v) {
54
+ return isObject(v) && typeof v.$param === "string" && Object.keys(v).length === 1;
55
+ }
56
+ /** Everything wrong with a parsed flow file; empty when it is valid. */
57
+ export function flowProblems(raw) {
58
+ if (!isObject(raw))
59
+ return ["must be a JSON object"];
60
+ const out = [];
61
+ if (typeof raw.version !== "number" || !Number.isInteger(raw.version) || raw.version < 1)
62
+ out.push("version must be a positive integer");
63
+ else if (raw.version > FLOW_FORMAT_VERSION)
64
+ return [`is format ${raw.version}, from a newer turno-browser (this one reads ${FLOW_FORMAT_VERSION}); update it`];
65
+ if (typeof raw.name !== "string" || !isValidFlowName(raw.name))
66
+ out.push("name must be a flow name");
67
+ if (typeof raw.identity !== "string")
68
+ out.push("identity must be a string");
69
+ if (raw.description !== undefined && typeof raw.description !== "string")
70
+ out.push("description must be a string");
71
+ const names = new Set();
72
+ if (!Array.isArray(raw.params))
73
+ out.push("params must be a list");
74
+ else
75
+ raw.params.forEach((p, i) => {
76
+ if (!isObject(p) || typeof p.name !== "string" || typeof p.sensitive !== "boolean")
77
+ out.push(`params[${i}] needs a name and sensitive`);
78
+ else {
79
+ names.add(p.name);
80
+ if (p.sensitive && p.default !== undefined)
81
+ out.push(`params[${i}] is sensitive and must not keep a default`);
82
+ if (p.default !== undefined && typeof p.default !== "string")
83
+ out.push(`params[${i}].default must be a string`);
84
+ }
85
+ });
86
+ if (!Array.isArray(raw.steps))
87
+ out.push("steps must be a list");
88
+ else {
89
+ if (raw.steps.length > MAX_FLOW_STEPS)
90
+ out.push(`steps holds more than ${MAX_FLOW_STEPS} steps`);
91
+ raw.steps.forEach((s, i) => {
92
+ if (!isObject(s) || typeof s.tool !== "string" || !isObject(s.args)) {
93
+ out.push(`steps[${i}] needs a tool and args`);
94
+ return;
95
+ }
96
+ for (const ref of paramRefs(s.args))
97
+ if (!names.has(ref))
98
+ out.push(`steps[${i}] uses parameter "${ref}", which params does not list`);
99
+ if (s.targets !== undefined) {
100
+ if (!isObject(s.targets))
101
+ out.push(`steps[${i}].targets must be an object`);
102
+ else
103
+ for (const [path, t] of Object.entries(s.targets)) {
104
+ if (!isObject(t) ||
105
+ !Array.isArray(t.locators) ||
106
+ t.locators.some((l) => !isObject(l) || typeof l.selector !== "string"))
107
+ out.push(`steps[${i}].targets.${path} needs a list of locators`);
108
+ }
109
+ }
110
+ });
111
+ }
112
+ return out;
113
+ }
114
+ /** The parameter names a value uses, at any depth. */
115
+ export function paramRefs(value) {
116
+ if (isParamRef(value))
117
+ return [value.$param];
118
+ if (Array.isArray(value))
119
+ return value.flatMap(paramRefs);
120
+ if (isObject(value))
121
+ return Object.values(value).flatMap(paramRefs);
122
+ return [];
123
+ }
124
+ /** A copy of `value` with every parameter slot replaced by its value. */
125
+ export function fillParams(value, values) {
126
+ if (isParamRef(value))
127
+ return values[value.$param];
128
+ if (Array.isArray(value))
129
+ return value.map((v) => fillParams(v, values));
130
+ if (isObject(value))
131
+ return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, fillParams(v, values)]));
132
+ return value;
133
+ }
134
+ /** Reads `a.b.0.c` of an object. */
135
+ export function getPath(obj, path) {
136
+ let cur = obj;
137
+ for (const key of path.split(".")) {
138
+ if (Array.isArray(cur))
139
+ cur = cur[Number(key)];
140
+ else if (isObject(cur))
141
+ cur = cur[key];
142
+ else
143
+ return undefined;
144
+ }
145
+ return cur;
146
+ }
147
+ /** Sets `a.b.0.c` of an object that already has every level but the last. */
148
+ export function setPath(obj, path, value) {
149
+ const keys = path.split(".");
150
+ let cur = obj;
151
+ for (const key of keys.slice(0, -1))
152
+ cur = Array.isArray(cur) ? cur[Number(key)] : cur[key];
153
+ const last = keys[keys.length - 1];
154
+ if (Array.isArray(cur))
155
+ cur[Number(last)] = value;
156
+ else if (isObject(cur))
157
+ cur[last] = value;
158
+ }
159
+ /**
160
+ * The parameter values a replay runs with: the given ones, then the defaults. `missing` lists
161
+ * the parameters with neither (every sensitive one not given), `unknown` the given names the
162
+ * flow does not have.
163
+ */
164
+ export function resolveParams(flow, given = {}) {
165
+ const values = {};
166
+ const missing = [];
167
+ for (const p of flow.params) {
168
+ const v = given[p.name] ?? p.default;
169
+ if (v === undefined)
170
+ missing.push(p);
171
+ else
172
+ values[p.name] = v;
173
+ }
174
+ const known = new Set(flow.params.map((p) => p.name));
175
+ return { values, missing, unknown: Object.keys(given).filter((k) => !known.has(k)) };
176
+ }
177
+ /** A step in a few words: `browser_click "Sign in" button`, `browser_navigate https://...`. */
178
+ export function describeStep(step) {
179
+ const t = step.targets?.target ?? step.targets?.startTarget;
180
+ const a = step.args;
181
+ if (step.tool === "browser_login")
182
+ return `browser_login site "${String(a.site)}"`;
183
+ if (step.tool === "browser_replay")
184
+ return `browser_replay flow "${String(a.flow)}"`;
185
+ if (step.tool === "browser_fill_form") {
186
+ const fields = Array.isArray(a.fields) ? a.fields.map((f) => f.name ?? "?") : [];
187
+ return `browser_fill_form ${fields.join(", ")}`;
188
+ }
189
+ const what = t ? (t.description ?? t.locators[0]?.selector) : (a.url ?? a.key ?? a.action ?? a.text ?? a.time);
190
+ const typed = isParamRef(a.text) ? ` with {${a.text.$param}}` : "";
191
+ return `${step.tool}${what === undefined ? "" : ` ${clip(String(what), 80)}`}${typed}`;
192
+ }
193
+ function clip(text, max) {
194
+ return text.length > max ? `${text.slice(0, max - 3)}...` : text;
195
+ }
196
+ /** Writes a flow (mode 600, through a rename). Validates first. */
197
+ export function writeFlow(id, flow, env = process.env) {
198
+ const problems = flowProblems(flow);
199
+ if (problems.length)
200
+ throw new FlowError(`flow "${flow.name}" ${problems.join("; ")}`);
201
+ const path = flowPath(id, flow.name, env);
202
+ mkdirSync(flowsDir(id, env), { recursive: true, mode: 0o700 });
203
+ const tmp = `${path}.${process.pid}.tmp`;
204
+ writeFileSync(tmp, `${JSON.stringify(flow, null, 2)}\n`, { mode: 0o600 });
205
+ renameSync(tmp, path);
206
+ return path;
207
+ }
208
+ /** A saved flow; throws a FlowError when there is none or it cannot be used. */
209
+ export function readFlow(id, name, env = process.env) {
210
+ const path = flowPath(id, name, env);
211
+ let text;
212
+ try {
213
+ text = readFileSync(path, "utf8");
214
+ }
215
+ catch (err) {
216
+ if (err.code === "ENOENT") {
217
+ const known = listFlows(id, env).map((f) => f.name);
218
+ throw new FlowError(`identity "${id}" has no flow "${name}"${known.length ? ` (saved: ${known.join(", ")})` : " (it has no saved flows)"}`);
219
+ }
220
+ throw new FlowError(`cannot read flow "${name}": ${err.message}`);
221
+ }
222
+ let raw;
223
+ try {
224
+ raw = JSON.parse(text);
225
+ }
226
+ catch {
227
+ throw new FlowError(`flow "${name}" (${path}) is not valid JSON`);
228
+ }
229
+ const problems = flowProblems(raw);
230
+ if (problems.length)
231
+ throw new FlowError(`flow "${name}" (${path}) ${problems.join("; ")}`);
232
+ return raw;
233
+ }
234
+ /** The identity's saved flows, newest first. Files that cannot be read are left out. */
235
+ export function listFlows(id, env = process.env) {
236
+ const dir = flowsDir(id, env);
237
+ if (!existsSync(dir))
238
+ return [];
239
+ const out = [];
240
+ for (const file of readdirSync(dir)) {
241
+ if (!file.endsWith(".json"))
242
+ continue;
243
+ const name = file.slice(0, -5);
244
+ if (!isValidFlowName(name))
245
+ continue;
246
+ let flow;
247
+ try {
248
+ flow = JSON.parse(readFileSync(join(dir, file), "utf8"));
249
+ if (flowProblems(flow).length)
250
+ continue;
251
+ }
252
+ catch {
253
+ continue;
254
+ }
255
+ const nav = flow.steps.find((s) => s.tool === "browser_navigate");
256
+ out.push({
257
+ name,
258
+ ...(flow.description ? { description: flow.description } : {}),
259
+ steps: flow.steps.length,
260
+ params: flow.params.map((p) => ({ name: p.name, sensitive: p.sensitive, hasDefault: p.default !== undefined })),
261
+ ...(nav && typeof nav.args.url === "string" ? { start: nav.args.url } : {}),
262
+ auto: name.startsWith(AUTO_PREFIX),
263
+ updated: flow.updated,
264
+ file: join(dir, file),
265
+ });
266
+ }
267
+ return out.sort((a, b) => b.updated.localeCompare(a.updated) || a.name.localeCompare(b.name));
268
+ }
269
+ /** Deletes a flow; false when there was none. */
270
+ export function removeFlow(id, name, env = process.env) {
271
+ const path = flowPath(id, name, env);
272
+ if (!existsSync(path))
273
+ return false;
274
+ rmSync(path, { force: true });
275
+ return true;
276
+ }
277
+ /** Keeps the newest `keep` flows the identity recorded by itself; returns how many went. */
278
+ export function rotateAutoFlows(id, keep, env = process.env) {
279
+ const dir = flowsDir(id, env);
280
+ if (!existsSync(dir))
281
+ return 0;
282
+ const auto = readdirSync(dir)
283
+ .filter((f) => f.startsWith(AUTO_PREFIX) && f.endsWith(".json"))
284
+ .map((f) => ({ f, t: statSync(join(dir, f)).mtimeMs }))
285
+ .sort((a, b) => b.t - a.t || b.f.localeCompare(a.f));
286
+ for (const { f } of auto.slice(keep))
287
+ rmSync(join(dir, f), { force: true });
288
+ return Math.max(0, auto.length - keep);
289
+ }
290
+ /** Removes every flow of an identity (when the identity goes). */
291
+ export function removeFlows(id, env = process.env) {
292
+ rmSync(flowsDir(id, env), { recursive: true, force: true });
293
+ }
294
+ //# sourceMappingURL=flows.js.map
@@ -0,0 +1,119 @@
1
+ import type { BrowserContext, Page } from "patchright-core";
2
+ import type { TabPolicy } from "./tuning.js";
3
+ /**
4
+ * The tab governor. Chrome keeps every page an agent or a site opened, and each one
5
+ * keeps running scripts, timers and network until somebody closes it; after a long session that
6
+ * is most of the browser's memory and CPU. Per session's browser context it:
7
+ *
8
+ * - caps the pages open at once (`max`): when a new page goes past it, the least recently used
9
+ * page closes, never the agent's current tab or the new page;
10
+ * - closes a popup (a page with an opener) that opened while no tool call was running, nor in
11
+ * the moments after one: ads and pop-unders, not the window a click of the agent opened
12
+ * (`popups: "close"`);
13
+ * - parks a page nobody used for `parkMs`: it goes to about:blank, which stops its scripts, and
14
+ * keeps its URL; the next call that uses that page (it is the current tab, or `browser_tabs`
15
+ * selects it) loads the URL again first. After `closeMs` unused the page closes.
16
+ *
17
+ * A page counts as used when it is the current tab at the end of a tool call, and when its main
18
+ * frame navigates (a person using a headed window). The current tab is never parked or closed,
19
+ * and neither is the last page.
20
+ *
21
+ * With `"sharing": "tabs"` several sessions work in one browser: the cap counts each session's
22
+ * pages apart (`owner`) and closes only that session's least recently used page, no session's
23
+ * current tab is parked or closed (`protected`), and each note goes to the session whose page it
24
+ * is about.
25
+ *
26
+ * With `ownedOnly` (attach mode, the user's own Chrome) it governs only the agent's pages:
27
+ * the ones handed to `own` and the ones that open during a tool call or in the moments after
28
+ * one. Pages that were open before, or that open between calls, are the user's: never counted,
29
+ * parked or closed, and no popup is closed.
30
+ */
31
+ /** A popup that opens this long after a tool call ended still counts as the call's. */
32
+ export declare const POPUP_GRACE_MS = 2000;
33
+ /** One session's view of the tabs: its current tab and the indexes `browser_tabs` uses. */
34
+ export interface TabView {
35
+ /** The page the stock tools act on (upstream's current tab), if any. */
36
+ current(): Page | undefined;
37
+ /** The pages in upstream's tab order (the indexes `browser_tabs` uses). */
38
+ tabs(): Page[];
39
+ }
40
+ export interface GovernorOptions extends TabView {
41
+ /** Pages never parked or closed: every session's current tab (default: `current()`). */
42
+ protected?(): Page[];
43
+ /** The session that holds a page; the cap counts each owner's pages apart (default: one group). */
44
+ owner?(page: Page): string | undefined;
45
+ /** Runs first for each page Chrome opens, before the popup check and the cap. */
46
+ adopt?(page: Page): Promise<void>;
47
+ now?: () => number;
48
+ /** Sweep for unused pages on a timer (the default); tests call `sweep()` themselves. */
49
+ timer?: boolean;
50
+ /** Govern only the agent's pages (see the class comment). */
51
+ ownedOnly?: boolean;
52
+ /** Told about each page counted as the agent's, with `ownedOnly`. */
53
+ onOwn?(page: Page): void;
54
+ }
55
+ export declare class TabGovernor {
56
+ private readonly context;
57
+ private readonly policy;
58
+ private readonly options;
59
+ private readonly pages;
60
+ private calls;
61
+ private lastCallEnd;
62
+ /** Notes for the next result, per owner of the page they are about (undefined: whoever calls next). */
63
+ private notes;
64
+ private timer;
65
+ private sweeping;
66
+ private readonly now;
67
+ private readonly adopting;
68
+ /** Pages opened during a call: the cap is applied once the call returns (`afterCall`). */
69
+ private readonly opened;
70
+ private readonly onPage;
71
+ constructor(context: BrowserContext, policy: TabPolicy, options: GovernorOptions);
72
+ start(): void;
73
+ dispose(): void;
74
+ /** Resolves once every page opened so far has been looked at (popup check, cap). */
75
+ settled(): Promise<void>;
76
+ /**
77
+ * The stock call returned: apply the cap to the pages it opened. Not during the call, since
78
+ * upstream reads every tab (title, console) to build the result and a page closed under it
79
+ * fails the call.
80
+ */
81
+ afterCall(): Promise<void>;
82
+ /** A tool call starts: nothing is swept and popups count as asked for until it ends. */
83
+ beginCall(): void;
84
+ /**
85
+ * Resolves once nothing the governor started before the call is still in flight: a popup
86
+ * check or a sweep may be closing a page right now, and upstream reads every tab (title,
87
+ * console) to build a result, so a page closing under the call fails it with "Target page,
88
+ * context or browser has been closed". Call after `beginCall`, which keeps new work from
89
+ * starting.
90
+ */
91
+ quiet(): Promise<void>;
92
+ /** A tool call ended: its current tab (of `view`, by default the governor's) was used now. */
93
+ endCall(view?: TabView): void;
94
+ /** Counts a page as the agent's (attach mode: the tab the host opens at connect). */
95
+ own(page: Page): void;
96
+ /** What the governor did since the last call, one line each, for the next tool result of `owner`. */
97
+ takeNotes(owner?: string): string[];
98
+ /** The URL a parked page will load again, or undefined when it is not parked. */
99
+ parkedUrl(page: Page): string | undefined;
100
+ /**
101
+ * Before a stock tool runs: when the page it is about to use is parked, load its URL again.
102
+ * That page is the tab `browser_tabs` is about to select, else the current tab.
103
+ */
104
+ prepare(name: string, args: Record<string, unknown>, view?: TabView): Promise<void>;
105
+ /** Marks parked tabs in a tab list of a tool result (`- 2: [](about:blank)`). */
106
+ annotateTabs(text: string, view?: TabView): string;
107
+ /** Parks and closes pages that went unused too long. Never while a tool call runs. */
108
+ sweep(): Promise<void>;
109
+ private sweepOnce;
110
+ private openPages;
111
+ private protectedPages;
112
+ private track;
113
+ /** A page Chrome just opened. */
114
+ private adopt;
115
+ private enforceCap;
116
+ private park;
117
+ private restore;
118
+ private note;
119
+ }