@peakflo/agent-harness 0.2.20-rc.1 → 0.2.20

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 (34) hide show
  1. package/README.md +78 -0
  2. package/dist/browser-broker/agent-actions.mjs +799 -0
  3. package/dist/browser-broker/browsers.mjs +1699 -0
  4. package/dist/browser-broker/credentials.mjs +211 -0
  5. package/dist/browser-broker/disk-guard.mjs +84 -0
  6. package/dist/browser-broker/egress.mjs +183 -0
  7. package/dist/browser-broker/input.mjs +270 -0
  8. package/dist/browser-broker/lease.mjs +547 -0
  9. package/dist/browser-broker/local-network.mjs +173 -0
  10. package/dist/browser-broker/local.mjs +158 -0
  11. package/dist/browser-broker/log.mjs +28 -0
  12. package/dist/browser-broker/network-policy.mjs +144 -0
  13. package/dist/browser-broker/os-users.mjs +493 -0
  14. package/dist/browser-broker/package.json +1 -0
  15. package/dist/browser-broker/protocol.mjs +321 -0
  16. package/dist/browser-broker/queue.mjs +37 -0
  17. package/dist/browser-broker/recorder-scripts.mjs +221 -0
  18. package/dist/browser-broker/recorder.mjs +438 -0
  19. package/dist/browser-broker/recording-store.mjs +493 -0
  20. package/dist/browser-broker/relay.mjs +399 -0
  21. package/dist/browser-broker/screencast.mjs +198 -0
  22. package/dist/browser-broker/state-store.mjs +112 -0
  23. package/dist/browser-broker/transfers.mjs +460 -0
  24. package/dist/control-plane.d.ts +6 -0
  25. package/dist/control-plane.js +10 -0
  26. package/dist/github-workspace.d.ts +2 -0
  27. package/dist/github-workspace.js +4 -0
  28. package/dist/harness.d.ts +1 -0
  29. package/dist/harness.js +24 -0
  30. package/dist/runtime/knowledge-tools.d.ts +1 -0
  31. package/dist/runtime/knowledge-tools.js +3 -0
  32. package/dist/runtime/local-browser.d.ts +33 -0
  33. package/dist/runtime/local-browser.js +135 -0
  34. package/package.json +5 -3
@@ -0,0 +1,1699 @@
1
+ /**
2
+ * One Chromium per chat, under that chat's own Unix user — and, since protocol
3
+ * v2, the AUTHORITY for that browser's input lease (lease.mjs).
4
+ *
5
+ * Every browser has ONE serial queue (queue.mjs). Agent commands, control
6
+ * changes (take, hand back, grant, grace expiry …), recording start/stop and
7
+ * the upload commit go through it, so a takeover lands only after the
8
+ * in-flight command settles, and a command is fenced against the lease as it
9
+ * is when the command reaches the FRONT of the queue. Person input is applied
10
+ * at once (not behind a slow agent wait) but only from the controlling
11
+ * connection of the current lease.
12
+ *
13
+ * Every lease change is persisted (state-store.mjs) BEFORE it is announced,
14
+ * then a `state` event (BrowserCoreState) goes to the API. Other changes (url,
15
+ * title, agentBusy, recording step count) are coalesced into one `state`
16
+ * event at most every STATE_COALESCE_MS.
17
+ *
18
+ * CDP is Playwright's default PIPE (fds 3/4). No --remote-debugging-port is
19
+ * ever passed; launchArgs() asserts it and chromium-as-user refuses it.
20
+ *
21
+ * Agent credentials (v3): `fill_credential` values live only in this root
22
+ * process, in the chat's RedactionSet (dropped when the browser closes).
23
+ * Every command result, error message, state url/title and recorder row
24
+ * passes through it, and agent screenshots mask the filled elements.
25
+ */
26
+ import { randomUUID } from 'node:crypto';
27
+ import path from 'node:path';
28
+ import {
29
+ BROWSER_COMMAND_NAMES,
30
+ BROWSER_CONTROL_OPS,
31
+ BROWSER_MAX_INPUT_EVENTS_PER_SECOND,
32
+ BROWSER_RECONNECT_GRACE_MS,
33
+ BROWSER_VIEWPORT,
34
+ BrokerError,
35
+ GAP,
36
+ TOOL_ERRORS,
37
+ recordingUrl
38
+ } from './protocol.mjs';
39
+ import * as lease from './lease.mjs';
40
+ import { SerialQueue } from './queue.mjs';
41
+ import * as actions from './agent-actions.mjs';
42
+ import { applyInput, RateLimiter } from './input.mjs';
43
+ import { Screencast } from './screencast.mjs';
44
+ import { Recorder } from './recorder.mjs';
45
+ import { sanitizeRecordingTarget } from './recorder-scripts.mjs';
46
+ import { CREDENTIAL_ID_RE, FIELD_RE, RedactionSet } from './credentials.mjs';
47
+ import { page as checkPage } from './recording-store.mjs';
48
+ import {
49
+ DISK_FULL_DOWNLOAD_MESSAGE,
50
+ DISK_FULL_NEW_DOWNLOAD_MESSAGE,
51
+ DISK_LOW_MESSAGE,
52
+ DOWNLOAD_POLL_MS,
53
+ DiskGuard,
54
+ PROFILE_CHECK_MS
55
+ } from './disk-guard.mjs';
56
+ import { BROWSERS_ROOT } from './os-users.mjs';
57
+ import { log, errorText } from './log.mjs';
58
+ import { trustEgressCa } from './egress.mjs';
59
+ import {
60
+ BROWSER_DENY_TCP_ARG,
61
+ enableFeaturesArg,
62
+ launchFailureMessage,
63
+ localTarget
64
+ } from './network-policy.mjs';
65
+
66
+ export { safeFileName } from './transfers.mjs';
67
+
68
+ export const CHROMIUM_WRAPPER =
69
+ '/usr/local/lib/pf-browser-broker/chromium-as-user';
70
+ export const DEFAULT_MAX_BROWSERS = 6;
71
+ export const STATE_COALESCE_MS = 250;
72
+ export const STATE_SAVE_FAILED =
73
+ 'Could not save the browser state; control did not change.';
74
+ export const STATE_SAVE_FAILED_OPEN =
75
+ 'Could not save the browser state; the browser was not opened.';
76
+
77
+ /**
78
+ * Chromium flags beyond Playwright's defaults. --no-sandbox: the sandbox has
79
+ * no unprivileged user namespaces (and the broker is not going to grant
80
+ * CAP_SYS_ADMIN to make the setuid sandbox work), so Chromium's own renderer
81
+ * sandbox cannot start. The CROSS-CHAT boundary is the per-chat Unix user,
82
+ * not the renderer sandbox: a compromised renderer runs as that chat's user
83
+ * and can read only that chat's profile. Playwright adds --no-sandbox itself
84
+ * (chromiumSandbox: false); it is listed here so the choice is explicit.
85
+ *
86
+ * NETWORK: Chromium uses the sandbox's network directly (no proxy, no
87
+ * per-uid firewall); the sandbox's own egress policy applies. Every Chromium
88
+ * process runs under pf-landlock-exec (chromium-as-user), which refuses TCP
89
+ * connect() to the sandbox's own service ports, and Local Network Access is
90
+ * switched on (enableFeaturesArg); see network-policy.mjs. The harness's
91
+ * loopback services also refuse browser uids themselves (agent-harness
92
+ * runtime/loopback-peer.ts), and the broker listens on nothing: CDP is a pipe.
93
+ */
94
+ export function launchArgs() {
95
+ const args = [
96
+ '--no-sandbox',
97
+ '--disable-dev-shm-usage',
98
+ '--no-pings',
99
+ '--disable-breakpad',
100
+ '--disable-crash-reporter',
101
+ enableFeaturesArg()
102
+ ];
103
+ if (args.some((arg) => /^--remote-debugging-(port|address)/.test(arg))) {
104
+ throw new Error('A debugging port is never allowed');
105
+ }
106
+ return args;
107
+ }
108
+
109
+ export function browserEnv(user) {
110
+ return {
111
+ PATH: '/usr/bin:/bin',
112
+ HOME: user.home,
113
+ TMPDIR: user.tmp,
114
+ XDG_CONFIG_HOME: path.join(user.home, '.config'),
115
+ XDG_CACHE_HOME: path.join(user.home, '.cache'),
116
+ XDG_DATA_HOME: path.join(user.home, '.local', 'share'),
117
+ XDG_RUNTIME_DIR: user.tmp,
118
+ FONTCONFIG_PATH: '/etc/fonts',
119
+ LANG: 'en_US.UTF-8',
120
+ TZ: process.env.TZ || 'UTC',
121
+ PF_BROWSER_UID: String(user.uid),
122
+ PF_BROWSER_GID: String(user.gid),
123
+ // Read and removed by chromium-as-user: pf-landlock-exec --deny-tcp-connect.
124
+ PF_BROWSER_DENY_TCP: BROWSER_DENY_TCP_ARG
125
+ };
126
+ }
127
+
128
+ function validActor(actor) {
129
+ if (!actor || typeof actor !== 'object') return false;
130
+ if (actor.kind === 'agent') return true;
131
+ return (
132
+ actor.kind === 'user' &&
133
+ typeof actor.userId === 'string' &&
134
+ actor.userId.length > 0 &&
135
+ actor.userId.length <= 200
136
+ );
137
+ }
138
+
139
+ function normaliseActor(actor) {
140
+ return actor.kind === 'user'
141
+ ? { kind: 'user', userId: actor.userId }
142
+ : { kind: 'agent' };
143
+ }
144
+
145
+ const iso = (ms) => (ms ? new Date(ms).toISOString() : null);
146
+
147
+ /** Most filled elements a chat keeps masked (oldest dropped beyond it). */
148
+ export const MAX_MASKED_FILLS = 100;
149
+ /** Marker the screenshot mask locator selects; re-applied before every shot. */
150
+ export const CREDENTIAL_MASK_ATTRIBUTE = 'data-pf-credential-mask';
151
+ /** Screenshot fields that are image bytes, not text: never rewritten. */
152
+ const SCREENSHOT_BINARY_KEYS = new Set(['data']);
153
+
154
+ /* -------------------------------------------------------------------------- */
155
+ /* One chat browser */
156
+ /* -------------------------------------------------------------------------- */
157
+
158
+ export class ChatBrowser {
159
+ queue = new SerialQueue();
160
+ pages = [];
161
+ activePage = null;
162
+ closing = false;
163
+ status = 'starting';
164
+ agentBusy = false;
165
+ lastActionAt = null;
166
+ lastError = null;
167
+ url = null;
168
+ title = null;
169
+ #updatedAt = Date.now();
170
+ #ids = new lease.IdLru();
171
+ #navCount = 0;
172
+ #handback = null;
173
+ #graceTimer = null;
174
+ #stateTimer = null;
175
+ #inputChain = Promise.resolve();
176
+ #inputCdp = null;
177
+ #inputCdpPage = null;
178
+ #inputState = { buttons: 0 };
179
+ #actionCdp = null;
180
+ #actionCdpPage = null;
181
+ #screencastWanted = false;
182
+ #screencastProfile = 'local';
183
+ #chooser = null;
184
+ #diskTimer = null;
185
+ #diskLow = false;
186
+ /** fill_credential values of this chat (root memory only). */
187
+ #redaction = new RedactionSet();
188
+ /** { page, handle } of every element fill_credential typed into. */
189
+ #fills = [];
190
+ #maskToken = randomUUID();
191
+
192
+ /**
193
+ * @param {{ sessionId: string, user: object, lease: object, startedBy: object|null,
194
+ * deps: { store, stateStore, transfers, emit, forget, remember, graceMs: () => number,
195
+ * now: () => number, relay, wrapper, disk?: DiskGuard,
196
+ * diskPollMs?: number, profileCheckMs?: number } }} options
197
+ */
198
+ constructor({ sessionId, user, lease: leaseState, startedBy, deps }) {
199
+ this.sessionId = sessionId;
200
+ this.user = user;
201
+ this.lease = leaseState;
202
+ this.startedBy = startedBy ?? null;
203
+ this.deps = deps;
204
+ this.viewport = { ...BROWSER_VIEWPORT };
205
+ this.limiter = new RateLimiter(BROWSER_MAX_INPUT_EVENTS_PER_SECOND);
206
+ this.screencast = new Screencast({
207
+ sessionId,
208
+ send: (frame) => deps.relay.sendBinary(frame),
209
+ bufferedAmount: () => deps.relay.bufferedAmount(),
210
+ openCdp: (page) => this.context.newCDPSession(page)
211
+ });
212
+ this.recorder = new Recorder({
213
+ sessionId,
214
+ chat: user.name,
215
+ store: deps.store,
216
+ pages: () => this.pages.slice(),
217
+ activePage: () => this.activePage,
218
+ openCdp: (page) => this.context.newCDPSession(page),
219
+ humanAllowed: () => this.lease.controller.kind === 'user',
220
+ redact: (value) => this.#redaction.redact(value),
221
+ onStep: () => this.#stateSoon(),
222
+ onFinished: (manifest) => this.#recordingFinished(manifest)
223
+ });
224
+ // The grace timer is armed by goLive(): a slow Chromium start must not
225
+ // eat the opening member's grace.
226
+ }
227
+
228
+ /** Launch finished: the opening member's grace starts now. */
229
+ goLive() {
230
+ this.status = 'live';
231
+ const c = this.lease.controller;
232
+ if (c.kind === 'user' && c.graceUntil !== null) {
233
+ this.lease = {
234
+ ...this.lease,
235
+ controller: { ...c, graceUntil: this.#now() + this.deps.graceMs() }
236
+ };
237
+ }
238
+ this.#armGrace();
239
+ this.#armDiskCheck();
240
+ this.emitState();
241
+ }
242
+
243
+ /* ------------------------------------------------------------------------ */
244
+ /* State */
245
+ /* ------------------------------------------------------------------------ */
246
+
247
+ #now() {
248
+ return this.deps.now();
249
+ }
250
+
251
+ #ctx() {
252
+ return {
253
+ now: this.#now(),
254
+ graceMs: this.deps.graceMs(),
255
+ newId: randomUUID
256
+ };
257
+ }
258
+
259
+ /** BrowserCoreState. */
260
+ coreState() {
261
+ const live = this.recorder.recordingId
262
+ ? this.deps.store.status(this.user.name)
263
+ : null;
264
+ const meta = live ? this.deps.store.meta(this.user.name, live.id) : null;
265
+ return {
266
+ sessionId: this.sessionId,
267
+ status: this.status,
268
+ ...lease.leaseView(this.lease),
269
+ startedBy: this.startedBy,
270
+ url: this.#redaction.text(this.url),
271
+ title: this.#redaction.text(this.title),
272
+ recording: live
273
+ ? {
274
+ id: live.id,
275
+ title: live.title,
276
+ startedAt: live.startedAt,
277
+ stepCount: live.stepCount,
278
+ startedByUserId: meta?.startedByUserId ?? null
279
+ }
280
+ : null,
281
+ agentBusy: this.agentBusy,
282
+ lastActionAt: iso(this.lastActionAt),
283
+ lastError: this.lastError,
284
+ updatedAt: new Date(this.#updatedAt).toISOString()
285
+ };
286
+ }
287
+
288
+ /** What the state file holds (no typed text, no query strings, no title). */
289
+ record() {
290
+ return {
291
+ sessionId: this.sessionId,
292
+ ...lease.persistable(this.lease),
293
+ startedBy: this.startedBy,
294
+ url: this.url ? recordingUrl(this.url) : null,
295
+ lastError: this.lastError,
296
+ updatedAt: new Date(this.#updatedAt).toISOString()
297
+ };
298
+ }
299
+
300
+ /** Best effort (url/title/status changes): a failed write is logged. */
301
+ persist() {
302
+ const record = this.record();
303
+ try {
304
+ this.deps.stateStore.write(this.user.name, record);
305
+ } catch (error) {
306
+ log.error('browser state could not be persisted', {
307
+ sessionId: this.sessionId,
308
+ error: errorText(error)
309
+ });
310
+ }
311
+ this.deps.remember(this.sessionId, record);
312
+ }
313
+
314
+ /** Write the record or throw (lease changes are fail-closed). */
315
+ persistStrict() {
316
+ const record = this.record();
317
+ this.deps.stateStore.write(this.user.name, record);
318
+ this.deps.remember(this.sessionId, record);
319
+ }
320
+
321
+ /** Persist and announce now (status changes; best effort persist). */
322
+ emitState() {
323
+ clearTimeout(this.#stateTimer);
324
+ this.#stateTimer = null;
325
+ this.#updatedAt = this.#now();
326
+ this.persist();
327
+ this.#announce();
328
+ }
329
+
330
+ #announce() {
331
+ this.deps.emit(this.sessionId, 'state', this.coreState());
332
+ }
333
+
334
+ /**
335
+ * Make `leaseState` the lease ONLY if it is saved first. A failed write
336
+ * rolls back in memory, announces nothing and throws `internal`, so a new
337
+ * epoch is never announced that a broker restart could issue again.
338
+ */
339
+ commitLease(leaseState, message = STATE_SAVE_FAILED) {
340
+ const previous = { lease: this.lease, updatedAt: this.#updatedAt };
341
+ clearTimeout(this.#stateTimer);
342
+ this.#stateTimer = null;
343
+ this.lease = leaseState;
344
+ this.#updatedAt = this.#now();
345
+ try {
346
+ this.persistStrict();
347
+ } catch (error) {
348
+ this.lease = previous.lease;
349
+ this.#updatedAt = previous.updatedAt;
350
+ log.error('browser lease could not be persisted; change rolled back', {
351
+ sessionId: this.sessionId,
352
+ error: errorText(error)
353
+ });
354
+ throw new BrokerError('internal', message);
355
+ }
356
+ this.#announce();
357
+ }
358
+
359
+ /** Coalesced announcement for url/title/agentBusy/step-count changes. */
360
+ #stateSoon() {
361
+ if (this.#stateTimer) return;
362
+ this.#stateTimer = setTimeout(() => {
363
+ this.#stateTimer = null;
364
+ if (!this.closing) this.emitState();
365
+ }, STATE_COALESCE_MS);
366
+ this.#stateTimer.unref?.();
367
+ }
368
+
369
+ #notice(notice) {
370
+ if (notice)
371
+ this.deps.emit(this.sessionId, 'notice', {
372
+ kind: notice.kind,
373
+ message: notice.message
374
+ });
375
+ }
376
+
377
+ #armGrace(minDelayMs = 0) {
378
+ clearTimeout(this.#graceTimer);
379
+ this.#graceTimer = null;
380
+ const deadline = lease.graceDeadline(this.lease);
381
+ if (deadline === null) return;
382
+ this.#graceTimer = setTimeout(
383
+ () => {
384
+ this.#graceTimer = null;
385
+ this.queue
386
+ .run(() =>
387
+ this.#transition(
388
+ lease.expireGrace(this.lease, this.#now(), this.#ctx())
389
+ )
390
+ )
391
+ .catch((error) => {
392
+ log.warn('grace expiry failed', {
393
+ sessionId: this.sessionId,
394
+ error: errorText(error)
395
+ });
396
+ // The lease was not changed (fail-closed persist): try again shortly.
397
+ if (!this.closing) this.#armGrace(1000);
398
+ });
399
+ },
400
+ Math.max(minDelayMs, deadline - this.#now()) + 5
401
+ );
402
+ this.#graceTimer.unref?.();
403
+ }
404
+
405
+ /* Free disk: the profile and downloads share the sandbox disk. */
406
+ #armDiskCheck() {
407
+ clearInterval(this.#diskTimer);
408
+ this.#diskTimer = null;
409
+ if (!this.deps.disk) return;
410
+ this.#diskTimer = setInterval(
411
+ () => this.checkDisk(),
412
+ this.deps.profileCheckMs ?? PROFILE_CHECK_MS
413
+ );
414
+ this.#diskTimer.unref?.();
415
+ }
416
+
417
+ /** Below the reserve: tell the people watching once; the browser keeps running. */
418
+ checkDisk() {
419
+ const low = !!this.deps.disk?.low();
420
+ if (low && !this.#diskLow && !this.closing) {
421
+ log.warn('sandbox disk nearly full', { sessionId: this.sessionId });
422
+ this.#notice({ kind: 'download', message: DISK_LOW_MESSAGE });
423
+ }
424
+ this.#diskLow = low;
425
+ return low;
426
+ }
427
+
428
+ /** Apply a lease result from lease.mjs (inside the queue). */
429
+ async #transition(result) {
430
+ if (!result.change) return { state: this.coreState() };
431
+ const page = this.activePage;
432
+ if (result.change === 'to_agent' && this.lease.controller.kind === 'user') {
433
+ // The person's debounced input reaches the recording while their lease
434
+ // still applies (the recorder accepts human events only under it).
435
+ await this.recorder.flushHuman().catch(() => undefined);
436
+ }
437
+ // Fail-closed: throws (and changes nothing) when the lease cannot be saved.
438
+ this.commitLease(result.state);
439
+ this.#handback = null;
440
+ this.#armGrace();
441
+ this.#notice(result.notice);
442
+ log.info('lease', {
443
+ sessionId: this.sessionId,
444
+ change: result.change,
445
+ epoch: this.lease.epoch
446
+ });
447
+ const value = { state: null };
448
+ if (
449
+ page &&
450
+ ['to_user', 'user_to_user', 'to_agent'].includes(result.change)
451
+ ) {
452
+ await page.evaluate(actions.CLEAR_REFS_SCRIPT).catch(() => undefined);
453
+ }
454
+ if (page && result.change === 'to_agent') {
455
+ // A fresh 20x snapshot, kept for the agent's next `snapshot` command
456
+ // (the gateway rewrites the held call into browser_snapshot).
457
+ const snapshot = await actions
458
+ .snapshot(page)
459
+ .then((value) => this.#redaction.redact(value))
460
+ .catch(() => null);
461
+ if (snapshot) {
462
+ this.#handback = {
463
+ epoch: this.lease.epoch,
464
+ nav: this.#navCount,
465
+ value: snapshot
466
+ };
467
+ value.snapshot = snapshot;
468
+ }
469
+ }
470
+ value.state = this.coreState();
471
+ return value;
472
+ }
473
+
474
+ /* ------------------------------------------------------------------------ */
475
+ /* Lifecycle */
476
+ /* ------------------------------------------------------------------------ */
477
+
478
+ async launch() {
479
+ // Restricted egress re-signs HTTPS with Daytona's CA: Chromium trusts it
480
+ // through the chat user's NSS database (no-op without that CA).
481
+ await this.deps.trustEgressCa?.(this.user);
482
+ const { chromium } = await import('playwright-core');
483
+ this.context = await (
484
+ this.deps.launchContext ??
485
+ ((options) =>
486
+ chromium.launchPersistentContext(this.user.profile, options))
487
+ )({
488
+ executablePath: this.deps.wrapper,
489
+ headless: true,
490
+ chromiumSandbox: false,
491
+ viewport: this.viewport,
492
+ deviceScaleFactor: 1,
493
+ acceptDownloads: true,
494
+ // A service worker outlives the page and fetches on its own; none is
495
+ // ever registered. No `permissions` either: Local Network Access is
496
+ // never granted.
497
+ serviceWorkers: 'block',
498
+ downloadsPath: this.user.downloads,
499
+ env: browserEnv(this.user),
500
+ args: launchArgs(),
501
+ handleSIGINT: false,
502
+ handleSIGTERM: false,
503
+ handleSIGHUP: false,
504
+ timeout: 60000
505
+ });
506
+ await this.deps.configureContext?.(this.context);
507
+ this.context.on('page', (page) => this.#addPage(page, true));
508
+ // LOGGING ONLY: nothing is blocked here (Landlock and LNA do that).
509
+ this.context.on('request', (request) => this.#noteLocalRequest(request));
510
+ this.context.on('close', () => this.#onContextClosed());
511
+ for (const page of this.context.pages()) this.#addPage(page, false);
512
+ if (!this.activePage) await this.context.newPage();
513
+ log.info('browser launched', {
514
+ sessionId: this.sessionId,
515
+ user: this.user.name
516
+ });
517
+ }
518
+
519
+ #localTargetsLogged = new Set();
520
+
521
+ /** Log, once per host:port, a page request aimed at a local address. */
522
+ #noteLocalRequest(request) {
523
+ const target = localTarget(request.url());
524
+ if (!target || this.#localTargetsLogged.has(target)) return;
525
+ if (this.#localTargetsLogged.size >= 50) return;
526
+ this.#localTargetsLogged.add(target);
527
+ log.info('page requested a local address', {
528
+ sessionId: this.sessionId,
529
+ target,
530
+ type: request.resourceType()
531
+ });
532
+ }
533
+
534
+ #addPage(page, makeActive) {
535
+ if (this.pages.includes(page)) return;
536
+ this.pages.push(page);
537
+ page.on('dialog', (dialog) => {
538
+ log.info('dialog auto-accepted', {
539
+ sessionId: this.sessionId,
540
+ type: dialog.type()
541
+ });
542
+ dialog.accept().catch(() => undefined);
543
+ });
544
+ page.on('download', (download) => void this.handleDownload(download));
545
+ page.on('filechooser', (chooser) => this.#onFileChooser(chooser));
546
+ page.on('framenavigated', (frame) => {
547
+ if (frame === page.mainFrame() && page === this.activePage)
548
+ this.#navigated();
549
+ });
550
+ page.on('crash', () => {
551
+ log.warn('page crashed', { sessionId: this.sessionId });
552
+ this.deps.emit(this.sessionId, 'crashed', { scope: 'page' });
553
+ });
554
+ page.on('close', () => void this.#onPageClosed(page));
555
+ if (makeActive || !this.activePage) void this.#activate(page);
556
+ if (this.recorder.recording) void this.recorder.attach(page);
557
+ }
558
+
559
+ async #activate(page) {
560
+ this.activePage = page;
561
+ this.#inputCdp = null;
562
+ this.#inputCdpPage = null;
563
+ if (this.#screencastWanted && !this.closing) {
564
+ await this.screencast
565
+ .start(page, this.#screencastProfile)
566
+ .catch((error) =>
567
+ log.warn('screencast restart failed', { error: errorText(error) })
568
+ );
569
+ }
570
+ this.#navigated();
571
+ }
572
+
573
+ async #onPageClosed(page) {
574
+ this.pages = this.pages.filter((p) => p !== page);
575
+ if (this.closing || page !== this.activePage) return;
576
+ const next = this.pages[this.pages.length - 1];
577
+ if (next) await this.#activate(next);
578
+ else if (this.context) await this.context.newPage().catch(() => undefined);
579
+ }
580
+
581
+ #onContextClosed() {
582
+ const unexpected = !this.closing;
583
+ this.closing = true;
584
+ this.#forgetCredentials();
585
+ clearTimeout(this.#graceTimer);
586
+ clearInterval(this.#diskTimer);
587
+ this.recorder.interrupt(GAP.browserClosed);
588
+ void this.screencast.stop();
589
+ if (unexpected) {
590
+ this.lastError = 'The browser exited unexpectedly.';
591
+ this.status = 'failed';
592
+ this.persist();
593
+ log.warn('browser exited unexpectedly', { sessionId: this.sessionId });
594
+ }
595
+ this.deps.forget(this.sessionId, this);
596
+ this.deps.emit(this.sessionId, unexpected ? 'crashed' : 'closed', {
597
+ scope: 'browser'
598
+ });
599
+ }
600
+
601
+ #navigated() {
602
+ const page = this.activePage;
603
+ if (!page) return;
604
+ this.#navCount++;
605
+ this.url = page.url();
606
+ void page
607
+ .title()
608
+ .catch(() => '')
609
+ .then((title) => {
610
+ if (page !== this.activePage) return;
611
+ this.url = page.url();
612
+ this.title = title || null;
613
+ this.#stateSoon();
614
+ });
615
+ }
616
+
617
+ async #cdpFor(kind) {
618
+ const page = this.activePage;
619
+ if (kind === 'input') {
620
+ if (!this.#inputCdp || this.#inputCdpPage !== page) {
621
+ this.#inputCdp = await this.context.newCDPSession(page);
622
+ this.#inputCdpPage = page;
623
+ }
624
+ return this.#inputCdp;
625
+ }
626
+ if (!this.#actionCdp || this.#actionCdpPage !== page) {
627
+ this.#actionCdp = await this.context.newCDPSession(page);
628
+ this.#actionCdpPage = page;
629
+ }
630
+ return this.#actionCdp;
631
+ }
632
+
633
+ #assertOpen() {
634
+ if (this.closing || this.status !== 'live')
635
+ throw new BrokerError('no_browser', 'The browser is not running.');
636
+ }
637
+
638
+ /* ------------------------------------------------------------------------ */
639
+ /* Queued requests */
640
+ /* ------------------------------------------------------------------------ */
641
+
642
+ control(msg) {
643
+ if (!BROWSER_CONTROL_OPS.includes(msg.op))
644
+ return Promise.reject(
645
+ new BrokerError('invalid_args', 'Unknown control op')
646
+ );
647
+ return this.queue.run(async () => {
648
+ this.#assertOpen();
649
+ const result = lease.control(this.lease, msg.op, msg.viewer, this.#ctx());
650
+ if (!result.ok)
651
+ throw new BrokerError(
652
+ result.error.code,
653
+ result.error.message,
654
+ this.coreState()
655
+ );
656
+ return this.#transition(result);
657
+ });
658
+ }
659
+
660
+ command(msg) {
661
+ if (!BROWSER_COMMAND_NAMES.includes(msg.name)) {
662
+ return Promise.reject(
663
+ new BrokerError(
664
+ 'invalid_args',
665
+ `Unknown command ${String(msg.name).slice(0, 40)}`
666
+ )
667
+ );
668
+ }
669
+ // Replays are refused on arrival, so a duplicate cannot slip in while the
670
+ // first copy still waits in the queue.
671
+ if (!this.#ids.add(msg.id)) {
672
+ return Promise.reject(
673
+ new BrokerError(
674
+ 'stale_sequence',
675
+ 'This command id was already used.',
676
+ this.coreState()
677
+ )
678
+ );
679
+ }
680
+ return this.queue.run(async () => {
681
+ this.#assertOpen();
682
+ const bad = lease.checkCommand(this.lease, msg.epoch);
683
+ if (bad) throw new BrokerError(bad.code, bad.message, this.coreState());
684
+ const handback = this.#handback;
685
+ this.#handback = null;
686
+ if (
687
+ msg.name === 'snapshot' &&
688
+ handback &&
689
+ handback.epoch === this.lease.epoch &&
690
+ handback.nav === this.#navCount
691
+ ) {
692
+ this.lastActionAt = this.#now();
693
+ this.#stateSoon();
694
+ return handback.value;
695
+ }
696
+ this.agentBusy = true;
697
+ this.#stateSoon();
698
+ try {
699
+ const result = await this.#run(
700
+ msg.name,
701
+ msg.args && typeof msg.args === 'object' ? msg.args : {}
702
+ );
703
+ return this.#redaction.redact(
704
+ result,
705
+ msg.name === 'screenshot' ? SCREENSHOT_BINARY_KEYS : null
706
+ );
707
+ } catch (error) {
708
+ // A message can quote the page (a URL, a selector, page text).
709
+ if (error instanceof BrokerError && this.#redaction.size > 0)
710
+ error.message = this.#redaction.text(error.message);
711
+ throw error;
712
+ } finally {
713
+ this.agentBusy = false;
714
+ this.lastActionAt = this.#now();
715
+ this.#stateSoon();
716
+ }
717
+ });
718
+ }
719
+
720
+ async #run(name, args) {
721
+ const page = this.activePage;
722
+ if (!page) throw new BrokerError('no_browser', 'The browser has no page.');
723
+ const recording = this.recorder.recording;
724
+ const label = actions.actionLabel(name, args);
725
+ switch (name) {
726
+ case 'preview_local':
727
+ if (!this.deps.previewLocal)
728
+ throw new BrokerError(
729
+ 'invalid_args',
730
+ 'Use this tool on a local runner.'
731
+ );
732
+ return actions.navigate(page, {
733
+ url: this.deps.previewLocal(args.port)
734
+ });
735
+ case 'snapshot':
736
+ return actions.snapshot(page);
737
+ case 'get':
738
+ return actions.get(page, args);
739
+ case 'wait':
740
+ return actions.wait(page, args);
741
+ case 'screenshot':
742
+ return actions.screenshot(page, args, {
743
+ cdp: await this.#cdpFor('action'),
744
+ viewport: this.viewport,
745
+ masks: await this.#screenshotMasks(page)
746
+ });
747
+ case 'fill_credential':
748
+ return this.#fillCredential(page, args);
749
+ case 'navigate':
750
+ if (recording) {
751
+ await this.recorder.recordStep({
752
+ source: 'agent',
753
+ action: label,
754
+ outcome: 'pending',
755
+ snapshotPhase: 'before-action'
756
+ });
757
+ }
758
+ return actions.navigate(page, args);
759
+ case 'back':
760
+ case 'forward':
761
+ case 'reload':
762
+ if (recording) {
763
+ await this.recorder.recordStep({
764
+ source: 'agent',
765
+ action: label,
766
+ outcome: 'pending',
767
+ snapshotPhase: 'before-action'
768
+ });
769
+ }
770
+ return actions.history(page, name, args, {
771
+ cdp: await this.#cdpFor('action')
772
+ });
773
+ case 'click':
774
+ case 'type':
775
+ case 'press_key':
776
+ case 'scroll':
777
+ return this.#recordedAction(page, name, args, label);
778
+ default:
779
+ throw new BrokerError(
780
+ 'invalid_args',
781
+ `Unknown command ${String(name).slice(0, 40)}`
782
+ );
783
+ }
784
+ }
785
+
786
+ /** 20x recordAction: describe the target first, run, then record after-action. */
787
+ async #recordedAction(page, name, args, label) {
788
+ const target =
789
+ typeof args.target === 'string' && args.target ? args.target : undefined;
790
+ let description;
791
+ if (target && this.recorder.recording) {
792
+ description = await this.recorder.describeTarget(
793
+ actions.targetSelector(target)
794
+ );
795
+ }
796
+ const run = {
797
+ click: () => actions.click(page, args),
798
+ type: () => actions.type(page, args),
799
+ press_key: () => actions.pressKey(page, args),
800
+ scroll: () => actions.scroll(page, args)
801
+ }[name];
802
+ let result;
803
+ let failure;
804
+ try {
805
+ result = await run();
806
+ } catch (error) {
807
+ failure = error;
808
+ }
809
+ if (this.recorder.recording) {
810
+ const commandTarget = target
811
+ ? sanitizeRecordingTarget(target)
812
+ : undefined;
813
+ const recordedTarget = commandTarget
814
+ ? `${actions.isRef(commandTarget) ? 'ref' : 'selector'} ${commandTarget}${description ? ` | ${description}` : ''}`.slice(
815
+ 0,
816
+ 300
817
+ )
818
+ : description;
819
+ await this.recorder.recordStep({
820
+ source: 'agent',
821
+ action: label,
822
+ target: recordedTarget,
823
+ outcome: failure ? 'error' : 'ok',
824
+ snapshotPhase: 'after-action'
825
+ });
826
+ }
827
+ if (failure) {
828
+ if (failure instanceof BrokerError) throw failure;
829
+ throw new BrokerError('internal', errorText(failure));
830
+ }
831
+ return result;
832
+ }
833
+
834
+ /**
835
+ * fill_credential (agent-actions.fillCredential does the checks). The
836
+ * value goes into the redaction set the moment it exists and the element
837
+ * into the screenshot mask list once typed; the recording gets a
838
+ * `fill_credential` step with credentialId + field and NO text.
839
+ */
840
+ async #fillCredential(page, args) {
841
+ const target =
842
+ typeof args.target === 'string' && args.target ? args.target : undefined;
843
+ const credentialId = CREDENTIAL_ID_RE.test(String(args.credentialId))
844
+ ? String(args.credentialId).toLowerCase()
845
+ : undefined;
846
+ const field = FIELD_RE.test(String(args.field))
847
+ ? String(args.field)
848
+ : undefined;
849
+ let description;
850
+ if (target && this.recorder.recording) {
851
+ description = await this.recorder.describeTarget(
852
+ actions.targetSelector(target)
853
+ );
854
+ }
855
+ let result;
856
+ let failure;
857
+ try {
858
+ result = await actions.fillCredential(page, args, {
859
+ cdp: await this.#cdpFor('action'),
860
+ resolve: (request) =>
861
+ this.deps.relay.call({
862
+ t: 'cred_resolve',
863
+ purpose: 'fill',
864
+ sessionId: this.sessionId,
865
+ nonce: request.nonce,
866
+ credentialId: request.credentialId,
867
+ field: request.field,
868
+ host: request.host,
869
+ frameHost: request.frameHost
870
+ }),
871
+ onValue: (value) => this.#redaction.add(value),
872
+ onTyped: (handle) => this.#rememberFill(page, handle)
873
+ });
874
+ } catch (error) {
875
+ failure = error;
876
+ }
877
+ // Ids, kinds and codes only.
878
+ log.info('fill_credential', {
879
+ sessionId: this.sessionId,
880
+ credentialId,
881
+ field,
882
+ ok: !failure,
883
+ code: failure ? (failure.code ?? 'internal') : undefined
884
+ });
885
+ if (this.recorder.recording) {
886
+ const commandTarget = target
887
+ ? sanitizeRecordingTarget(target)
888
+ : undefined;
889
+ const recordedTarget = commandTarget
890
+ ? `${actions.isRef(commandTarget) ? 'ref' : 'selector'} ${commandTarget}${description ? ` | ${description}` : ''}`.slice(
891
+ 0,
892
+ 300
893
+ )
894
+ : description;
895
+ await this.recorder.recordStep({
896
+ source: 'agent',
897
+ action: 'fill_credential',
898
+ target: recordedTarget,
899
+ credentialId,
900
+ field,
901
+ outcome: failure ? 'error' : 'ok',
902
+ snapshotPhase: 'after-action'
903
+ });
904
+ }
905
+ if (failure) {
906
+ if (failure instanceof BrokerError) throw failure;
907
+ throw new BrokerError('internal', errorText(failure));
908
+ }
909
+ return result;
910
+ }
911
+
912
+ #rememberFill(page, handle) {
913
+ if (!handle) return;
914
+ this.#fills.push({ page, handle });
915
+ while (this.#fills.length > MAX_MASKED_FILLS) {
916
+ const old = this.#fills.shift();
917
+ old.handle.dispose?.().catch?.(() => undefined);
918
+ }
919
+ }
920
+
921
+ /**
922
+ * The mask for an agent screenshot of `page`: every filled element that is
923
+ * still in the document, found by its ElementHandle (so a changed id,
924
+ * class or type=password -> text does not unmask it). The marker attribute
925
+ * is put back before every shot in case the page removed it.
926
+ */
927
+ async #screenshotMasks(page) {
928
+ const keep = [];
929
+ const boxes = [];
930
+ let masked = 0;
931
+ for (const fill of this.#fills) {
932
+ if (fill.page !== page) {
933
+ keep.push(fill);
934
+ continue;
935
+ }
936
+ let connected = false;
937
+ try {
938
+ connected = await fill.handle.evaluate(
939
+ (el, [name, token]) => {
940
+ if (!el.isConnected) return false;
941
+ el.setAttribute(name, token);
942
+ return true;
943
+ },
944
+ [CREDENTIAL_MASK_ATTRIBUTE, this.#maskToken]
945
+ );
946
+ } catch {
947
+ connected = false; // navigated away or page closed
948
+ }
949
+ if (!connected) {
950
+ fill.handle.dispose?.().catch?.(() => undefined);
951
+ continue;
952
+ }
953
+ keep.push(fill);
954
+ masked++;
955
+ const box = await fill.handle.boundingBox().catch(() => null);
956
+ if (box && box.width > 0 && box.height > 0) boxes.push(box);
957
+ }
958
+ this.#fills = keep;
959
+ if (masked === 0) return null;
960
+ return {
961
+ locators: [
962
+ page.locator(`[${CREDENTIAL_MASK_ATTRIBUTE}="${this.#maskToken}"]`)
963
+ ],
964
+ boxes
965
+ };
966
+ }
967
+
968
+ #forgetCredentials() {
969
+ this.#redaction.clear();
970
+ for (const fill of this.#fills)
971
+ fill.handle.dispose?.().catch?.(() => undefined);
972
+ this.#fills = [];
973
+ }
974
+
975
+ recordingStart(msg) {
976
+ return this.queue.run(async () => {
977
+ this.#assertOpen();
978
+ if (this.recorder.recording || this.deps.store.status(this.user.name)) {
979
+ throw new BrokerError('recording_active', TOOL_ERRORS.alreadyRecording);
980
+ }
981
+ const userId =
982
+ typeof msg.userId === 'string' && msg.userId
983
+ ? msg.userId.slice(0, 200)
984
+ : null;
985
+ let manifest;
986
+ try {
987
+ manifest = await this.recorder.start(
988
+ randomUUID(),
989
+ typeof msg.title === 'string' ? msg.title : '',
990
+ userId
991
+ );
992
+ } catch (error) {
993
+ if (error instanceof BrokerError) throw error;
994
+ log.warn('recording start failed', {
995
+ sessionId: this.sessionId,
996
+ error: errorText(error)
997
+ });
998
+ throw new BrokerError('internal', 'Could not start browser recording');
999
+ }
1000
+ this.emitState();
1001
+ this.#notice({
1002
+ kind: 'recording_started',
1003
+ message: 'Recording browser steps.'
1004
+ });
1005
+ return { recording: manifest };
1006
+ });
1007
+ }
1008
+
1009
+ recordingStop() {
1010
+ return this.queue.run(async () => {
1011
+ if (!this.recorder.recording) {
1012
+ // Idempotent: a repeated Stop answers with the recording it stopped.
1013
+ const last = this.deps.store.last(this.user.name);
1014
+ if (last && last.status !== 'recording') return { recording: last };
1015
+ throw new BrokerError('not_recording', TOOL_ERRORS.notRecording);
1016
+ }
1017
+ try {
1018
+ return {
1019
+ recording: await this.recorder.stop({ browserAlive: !this.closing })
1020
+ };
1021
+ } catch (error) {
1022
+ log.warn('recording stop failed', {
1023
+ sessionId: this.sessionId,
1024
+ error: errorText(error)
1025
+ });
1026
+ throw new BrokerError('internal', 'Could not save browser recording');
1027
+ }
1028
+ });
1029
+ }
1030
+
1031
+ #recordingFinished(manifest) {
1032
+ this.deps.emit(this.sessionId, 'recording_finished', {
1033
+ recordingId: manifest.id,
1034
+ status: manifest.status,
1035
+ manifest
1036
+ });
1037
+ this.#notice(
1038
+ manifest.status === 'saved'
1039
+ ? {
1040
+ kind: 'recording_saved',
1041
+ message: `Recording saved · ${manifest.stepCount ?? 0} steps.`
1042
+ }
1043
+ : {
1044
+ kind: 'recording_interrupted',
1045
+ message: 'The recording stopped early. Its saved steps are kept.'
1046
+ }
1047
+ );
1048
+ if (!this.closing) this.emitState();
1049
+ }
1050
+
1051
+ /** upload_begin: the person in control, at the current epoch. */
1052
+ uploadBegin(msg) {
1053
+ this.#assertOpen();
1054
+ const bad = lease.checkController(this.lease, msg.viewer, msg.epoch);
1055
+ if (bad) throw new BrokerError(bad.code, bad.message, this.coreState());
1056
+ return this.deps.transfers.beginUpload({
1057
+ sessionId: this.sessionId,
1058
+ uploadId: msg.uploadId,
1059
+ fileName: msg.fileName,
1060
+ size: msg.size
1061
+ });
1062
+ }
1063
+
1064
+ uploadCommit(msg) {
1065
+ return this.queue.run(async () => {
1066
+ this.#assertOpen();
1067
+ const bad = lease.checkController(this.lease, msg.viewer, msg.epoch);
1068
+ if (bad) throw new BrokerError(bad.code, bad.message, this.coreState());
1069
+ const chooser = this.#chooser;
1070
+ if (!chooser)
1071
+ throw new BrokerError('invalid_args', 'No file chooser is open.');
1072
+ const file = await this.deps.transfers.commitUpload({
1073
+ sessionId: this.sessionId,
1074
+ uploadId: msg.uploadId,
1075
+ parts: msg.parts,
1076
+ user: this.user
1077
+ });
1078
+ await chooser.setFiles(file.path);
1079
+ this.#chooser = null;
1080
+ log.info('upload set', { sessionId: this.sessionId });
1081
+ return { ok: true, name: file.name, size: file.size };
1082
+ });
1083
+ }
1084
+
1085
+ /**
1086
+ * The API socket dropped: no viewer connection can be trusted any more, so
1087
+ * a person's lease waits in grace for their viewer to `connect` again (the
1088
+ * API replays `connect` for live viewers after hello).
1089
+ */
1090
+ relayLost() {
1091
+ return this.queue.run(async () => {
1092
+ const c = this.lease.controller;
1093
+ if (this.closing || c.kind !== 'user' || c.connectionId === null)
1094
+ return null;
1095
+ const viewer = {
1096
+ userId: c.userId,
1097
+ connectionId: c.connectionId,
1098
+ name: c.name
1099
+ };
1100
+ return this.#transition(
1101
+ lease.control(this.lease, 'disconnect', viewer, this.#ctx())
1102
+ );
1103
+ });
1104
+ }
1105
+
1106
+ fileChooserCancel() {
1107
+ return this.queue.run(async () => {
1108
+ this.#chooser = null;
1109
+ return { ok: true };
1110
+ });
1111
+ }
1112
+
1113
+ #onFileChooser(chooser) {
1114
+ this.#chooser = chooser;
1115
+ this.deps.emit(this.sessionId, 'file_chooser', {
1116
+ multiple: chooser.isMultiple(),
1117
+ controller: this.lease.controller.kind
1118
+ });
1119
+ }
1120
+
1121
+ /**
1122
+ * A page started a download (Playwright `download` event). No size cap
1123
+ * (owner decision); the disk guard stops it instead: refused at once when
1124
+ * free disk is already below the reserve, cancelled (and its partial file
1125
+ * deleted) when free disk drops below the reserve while it runs.
1126
+ */
1127
+ async handleDownload(download) {
1128
+ const suggested = download.suggestedFilename();
1129
+ const name = String(suggested || 'download').slice(0, 180);
1130
+ const disk = this.deps.disk;
1131
+ if (disk && this.checkDisk()) {
1132
+ await download.cancel().catch(() => undefined);
1133
+ await download.delete().catch(() => undefined);
1134
+ log.warn('download refused: sandbox disk nearly full', {
1135
+ sessionId: this.sessionId
1136
+ });
1137
+ this.#downloadStopped(name, DISK_FULL_NEW_DOWNLOAD_MESSAGE);
1138
+ return;
1139
+ }
1140
+ let stoppedForDisk = false;
1141
+ let poll = null;
1142
+ if (disk) {
1143
+ poll = setInterval(() => {
1144
+ if (stoppedForDisk || !disk.low()) return;
1145
+ stoppedForDisk = true;
1146
+ clearInterval(poll);
1147
+ download.cancel().catch(() => undefined);
1148
+ }, this.deps.diskPollMs ?? DOWNLOAD_POLL_MS);
1149
+ poll.unref?.();
1150
+ }
1151
+ let file = null;
1152
+ let failure = null;
1153
+ try {
1154
+ file = await download.path();
1155
+ } catch (error) {
1156
+ failure = error;
1157
+ }
1158
+ clearInterval(poll);
1159
+ if (stoppedForDisk) {
1160
+ // The partial (or just-finished) file goes: the disk is nearly full.
1161
+ await download.delete().catch(() => undefined);
1162
+ log.warn('download stopped: sandbox disk nearly full', {
1163
+ sessionId: this.sessionId
1164
+ });
1165
+ this.#downloadStopped(name, DISK_FULL_DOWNLOAD_MESSAGE);
1166
+ return;
1167
+ }
1168
+ try {
1169
+ if (failure) throw failure;
1170
+ if (!file) throw new Error('download did not finish');
1171
+ const saved = await this.deps.transfers.saveDownload(
1172
+ this.user,
1173
+ file,
1174
+ suggested
1175
+ );
1176
+ this.deps.emit(this.sessionId, 'download', saved);
1177
+ log.info('download kept', {
1178
+ sessionId: this.sessionId,
1179
+ size: saved.size
1180
+ });
1181
+ await download.delete().catch(() => undefined);
1182
+ } catch (error) {
1183
+ log.warn('download failed', {
1184
+ sessionId: this.sessionId,
1185
+ error: errorText(error)
1186
+ });
1187
+ this.deps.emit(this.sessionId, 'download', {
1188
+ downloadId: null,
1189
+ name,
1190
+ size: 0,
1191
+ error: 'The download could not be saved.'
1192
+ });
1193
+ }
1194
+ }
1195
+
1196
+ #downloadStopped(name, message) {
1197
+ this.deps.emit(this.sessionId, 'download', {
1198
+ downloadId: null,
1199
+ name,
1200
+ size: 0,
1201
+ error: message
1202
+ });
1203
+ this.#notice({ kind: 'download', message });
1204
+ }
1205
+
1206
+ /* ------------------------------------------------------------------------ */
1207
+ /* Pushes */
1208
+ /* ------------------------------------------------------------------------ */
1209
+
1210
+ input(msg) {
1211
+ const reject = (code, message) =>
1212
+ this.deps.emit(this.sessionId, 'input_rejected', {
1213
+ seq: msg.seq ?? null,
1214
+ code,
1215
+ message
1216
+ });
1217
+ if (this.closing || this.status !== 'live')
1218
+ return reject('no_browser', 'The browser is not running.');
1219
+ if (!this.limiter.take())
1220
+ return reject('invalid_args', 'Too many input events.');
1221
+ const fenced = lease.acceptInput(this.lease, msg);
1222
+ if (!fenced.ok) return reject(fenced.error.code, fenced.error.message);
1223
+ this.lease = fenced.state;
1224
+ const event = msg.event;
1225
+ // The lease this input was accepted under. A control change (take, hand
1226
+ // back, grant, revoke, grace expiry) can land while earlier input is still
1227
+ // being applied; queued input from the old lease is then dropped.
1228
+ const accepted = { epoch: this.lease.epoch, leaseId: this.lease.leaseId };
1229
+ this.#inputChain = this.#inputChain
1230
+ .then(async () => {
1231
+ if (this.closing || !this.activePage) return;
1232
+ if (
1233
+ this.lease.epoch !== accepted.epoch ||
1234
+ this.lease.leaseId !== accepted.leaseId
1235
+ ) {
1236
+ reject(
1237
+ 'stale_lease',
1238
+ 'Control changed before this input was applied.'
1239
+ );
1240
+ return;
1241
+ }
1242
+ await applyInput(event, {
1243
+ cdp: await this.#cdpFor('input'),
1244
+ page: this.activePage,
1245
+ viewport: this.viewport,
1246
+ state: this.#inputState
1247
+ });
1248
+ })
1249
+ .catch((error) => {
1250
+ reject(
1251
+ error instanceof BrokerError ? error.code : 'internal',
1252
+ error instanceof BrokerError ? error.message : 'Input failed.'
1253
+ );
1254
+ });
1255
+ }
1256
+
1257
+ async setScreencast(on, profile = 'local') {
1258
+ this.#screencastWanted = !!on;
1259
+ this.#screencastProfile = profile === 'remote' ? 'remote' : 'local';
1260
+ if (on && this.activePage && !this.closing)
1261
+ await this.screencast.start(this.activePage, this.#screencastProfile);
1262
+ else await this.screencast.stop();
1263
+ }
1264
+
1265
+ /** Stop timers without touching the page (tests, failed launch). */
1266
+ dispose() {
1267
+ clearTimeout(this.#graceTimer);
1268
+ clearTimeout(this.#stateTimer);
1269
+ clearInterval(this.#diskTimer);
1270
+ this.#graceTimer = null;
1271
+ this.#stateTimer = null;
1272
+ this.#diskTimer = null;
1273
+ }
1274
+
1275
+ async close() {
1276
+ if (this.closing) return;
1277
+ // Let the in-flight command finish first.
1278
+ await this.queue
1279
+ .run(async () => {
1280
+ this.status = 'stopping';
1281
+ this.emitState();
1282
+ if (this.recorder.recording) this.recorder.interrupt(GAP.browserClosed);
1283
+ })
1284
+ .catch(() => undefined);
1285
+ this.closing = true;
1286
+ clearTimeout(this.#graceTimer);
1287
+ clearTimeout(this.#stateTimer);
1288
+ clearInterval(this.#diskTimer);
1289
+ await this.screencast.stop();
1290
+ await this.context?.close().catch(() => undefined);
1291
+ this.#forgetCredentials();
1292
+ }
1293
+ }
1294
+
1295
+ /* -------------------------------------------------------------------------- */
1296
+ /* Manager */
1297
+ /* -------------------------------------------------------------------------- */
1298
+
1299
+ export class BrowserManager {
1300
+ #browsers = new Map();
1301
+ #opening = new Map();
1302
+ /** sessionId -> last persisted record (also for closed browsers): epochs continue. */
1303
+ #records = new Map();
1304
+
1305
+ /**
1306
+ * @param {{ osUsers, store, stateStore, transfers, relay,
1307
+ * wrapper?: string, maxBrowsers?: number, graceMs?: number, now?: () => number }} deps
1308
+ */
1309
+ constructor(deps) {
1310
+ const graceMs =
1311
+ Number.isSafeInteger(deps.graceMs) && deps.graceMs > 0
1312
+ ? deps.graceMs
1313
+ : BROWSER_RECONNECT_GRACE_MS;
1314
+ this.graceMs = graceMs;
1315
+ this.deps = {
1316
+ wrapper: CHROMIUM_WRAPPER,
1317
+ trustEgressCa,
1318
+ maxBrowsers: DEFAULT_MAX_BROWSERS,
1319
+ now: Date.now,
1320
+ disk: new DiskGuard({ path: BROWSERS_ROOT }),
1321
+ ...deps,
1322
+ graceMs: () => this.graceMs,
1323
+ emit: (sessionId, kind, data) =>
1324
+ deps.relay.send({ t: 'event', sessionId, kind, data }),
1325
+ forget: (sessionId, browser) => {
1326
+ if (this.#browsers.get(sessionId) === browser)
1327
+ this.#browsers.delete(sessionId);
1328
+ },
1329
+ remember: (sessionId, record) => this.#records.set(sessionId, record)
1330
+ };
1331
+ }
1332
+
1333
+ /**
1334
+ * After a broker restart: every persisted lease continues ABOVE its epoch
1335
+ * (lease.restoreLease), and the bumped record is written back at once.
1336
+ */
1337
+ restore() {
1338
+ const now = this.deps.now();
1339
+ for (const [sessionId, record] of this.deps.stateStore.loadAll()) {
1340
+ if (record.wiped) {
1341
+ this.#records.set(sessionId, {
1342
+ sessionId,
1343
+ epoch: record.epoch,
1344
+ wiped: true,
1345
+ user: record.user
1346
+ });
1347
+ continue;
1348
+ }
1349
+ const restored = lease.restoreLease(record, {
1350
+ now,
1351
+ graceMs: this.graceMs,
1352
+ newId: randomUUID
1353
+ });
1354
+ const next = {
1355
+ ...record,
1356
+ ...lease.persistable(restored),
1357
+ updatedAt: new Date(now).toISOString()
1358
+ };
1359
+ try {
1360
+ this.deps.stateStore.write(record.user, next);
1361
+ } catch (error) {
1362
+ log.warn('restored state could not be written', {
1363
+ error: errorText(error)
1364
+ });
1365
+ }
1366
+ this.#records.set(sessionId, next);
1367
+ }
1368
+ return this.#records.size;
1369
+ }
1370
+
1371
+ setGraceMs(ms) {
1372
+ if (Number.isSafeInteger(ms) && ms > 0) this.graceMs = ms;
1373
+ }
1374
+
1375
+ get size() {
1376
+ return this.#browsers.size;
1377
+ }
1378
+
1379
+ get(sessionId) {
1380
+ return this.#browsers.get(sessionId) ?? null;
1381
+ }
1382
+
1383
+ record(sessionId) {
1384
+ return this.#records.get(sessionId) ?? null;
1385
+ }
1386
+
1387
+ #require(sessionId) {
1388
+ const browser = this.#browsers.get(sessionId);
1389
+ if (!browser || browser.closing)
1390
+ throw new BrokerError('no_browser', 'No browser is open for this chat.');
1391
+ return browser;
1392
+ }
1393
+
1394
+ /** BrowserCoreState of every browser that is starting or live. */
1395
+ states() {
1396
+ return [
1397
+ ...this.#browsers.values(),
1398
+ ...[...this.#opening.values()].map((o) => o.browser)
1399
+ ]
1400
+ .filter((b) => b instanceof ChatBrowser && !b.closing)
1401
+ .map((b) => b.coreState());
1402
+ }
1403
+
1404
+ /** The chat's recordings/downloads owner, without creating a user. */
1405
+ #userOf(sessionId) {
1406
+ const live = this.#browsers.get(sessionId);
1407
+ if (live) return live.user;
1408
+ return this.deps.osUsers.lookup(sessionId);
1409
+ }
1410
+
1411
+ async open(msg) {
1412
+ if (
1413
+ typeof msg.sessionId !== 'string' ||
1414
+ !msg.sessionId ||
1415
+ msg.sessionId.length > 200
1416
+ ) {
1417
+ throw new BrokerError('invalid_args', 'sessionId is required');
1418
+ }
1419
+ if (
1420
+ msg.startedBy !== undefined &&
1421
+ msg.startedBy !== null &&
1422
+ !validActor(msg.startedBy)
1423
+ ) {
1424
+ throw new BrokerError(
1425
+ 'invalid_args',
1426
+ 'startedBy must be an agent or a user'
1427
+ );
1428
+ }
1429
+ const initial = msg.initialController ?? null;
1430
+ if (
1431
+ initial !== null &&
1432
+ lease.invalidViewer(initial, { needConnection: false })
1433
+ ) {
1434
+ throw new BrokerError(
1435
+ 'invalid_args',
1436
+ 'initialController must be a viewer identity'
1437
+ );
1438
+ }
1439
+ const existing = this.#browsers.get(msg.sessionId);
1440
+ if (existing && !existing.closing) return existing.coreState();
1441
+ const opening = this.#opening.get(msg.sessionId);
1442
+ if (opening) {
1443
+ await opening.ready;
1444
+ const opened = this.#browsers.get(msg.sessionId);
1445
+ if (!opened)
1446
+ throw new BrokerError('internal', 'The browser could not start.');
1447
+ return opened.coreState();
1448
+ }
1449
+ if (this.#browsers.size + this.#opening.size >= this.deps.maxBrowsers) {
1450
+ throw new BrokerError(
1451
+ 'browser_limit',
1452
+ `This sandbox already runs ${this.deps.maxBrowsers} browsers.`
1453
+ );
1454
+ }
1455
+ // Reserve the slot synchronously; the user is created inside.
1456
+ let resolveReady;
1457
+ const placeholder = {
1458
+ ready: new Promise((resolve) => (resolveReady = resolve)),
1459
+ browser: null
1460
+ };
1461
+ this.#opening.set(msg.sessionId, placeholder);
1462
+ try {
1463
+ const user = await this.deps.osUsers.ensure(msg.sessionId);
1464
+ const leaseState = lease.openLease(this.#records.get(msg.sessionId), {
1465
+ initialController: initial,
1466
+ now: this.deps.now(),
1467
+ graceMs: this.graceMs,
1468
+ newId: randomUUID
1469
+ });
1470
+ const browser = new ChatBrowser({
1471
+ sessionId: msg.sessionId,
1472
+ user,
1473
+ lease: leaseState,
1474
+ startedBy: msg.startedBy ? normaliseActor(msg.startedBy) : null,
1475
+ deps: this.deps
1476
+ });
1477
+ placeholder.browser = browser;
1478
+ // The new epoch must be saved before anyone hears of it (fail-closed).
1479
+ browser.commitLease(leaseState, STATE_SAVE_FAILED_OPEN);
1480
+ try {
1481
+ await browser.launch();
1482
+ } catch (error) {
1483
+ log.error('browser launch failed', {
1484
+ sessionId: msg.sessionId,
1485
+ error: errorText(error)
1486
+ });
1487
+ const message = launchFailureMessage(error);
1488
+ browser.status = 'failed';
1489
+ browser.lastError = message;
1490
+ browser.emitState();
1491
+ browser.closing = true;
1492
+ await browser.context?.close().catch(() => undefined);
1493
+ throw new BrokerError('internal', message);
1494
+ }
1495
+ this.#browsers.set(msg.sessionId, browser);
1496
+ browser.goLive();
1497
+ return browser.coreState();
1498
+ } finally {
1499
+ this.#opening.delete(msg.sessionId);
1500
+ resolveReady();
1501
+ }
1502
+ }
1503
+
1504
+ async close(msg) {
1505
+ const browser = this.#browsers.get(msg.sessionId);
1506
+ if (browser) {
1507
+ await browser.close();
1508
+ this.#browsers.delete(msg.sessionId);
1509
+ }
1510
+ // keepRecordings (archive / delete of a chat): wipe the profile, downloads
1511
+ // and uploads but keep the chat's saved recordings; only the explicit
1512
+ // "clear browser" action (keepRecordings absent/false) deletes them.
1513
+ const keepRecordings = msg.keepRecordings === true;
1514
+ if (msg.wipe) {
1515
+ const user = this.#userOf(msg.sessionId);
1516
+ if (user) {
1517
+ if (!keepRecordings) this.deps.store.removeChat(user.name);
1518
+ const epoch =
1519
+ this.#records.get(msg.sessionId)?.epoch ?? browser?.lease.epoch ?? 0;
1520
+ try {
1521
+ this.deps.stateStore.tombstone(user.name, msg.sessionId, epoch);
1522
+ } catch (error) {
1523
+ log.warn('state tombstone failed', { error: errorText(error) });
1524
+ }
1525
+ this.#records.set(msg.sessionId, {
1526
+ sessionId: msg.sessionId,
1527
+ epoch,
1528
+ wiped: true,
1529
+ user: user.name
1530
+ });
1531
+ await this.deps.osUsers.wipe(msg.sessionId);
1532
+ }
1533
+ }
1534
+ return {
1535
+ closed: true,
1536
+ wiped: !!msg.wipe,
1537
+ keptRecordings: !!msg.wipe && keepRecordings
1538
+ };
1539
+ }
1540
+
1541
+ /** `state {sessionId}` -> BrowserCoreState | null; `state {sessionId: null}` -> BrowserCoreState[]. */
1542
+ state(msg) {
1543
+ if (msg.sessionId === null || msg.sessionId === undefined)
1544
+ return this.states();
1545
+ const browser =
1546
+ this.#browsers.get(msg.sessionId) ??
1547
+ this.#opening.get(msg.sessionId)?.browser;
1548
+ return browser && !browser.closing ? browser.coreState() : null;
1549
+ }
1550
+
1551
+ recordingRead(msg) {
1552
+ const user = this.#userOf(msg.sessionId);
1553
+ const { store } = this.deps;
1554
+ switch (msg.op) {
1555
+ case 'list':
1556
+ if (!user) {
1557
+ checkPage(msg.offset, msg.limit);
1558
+ return { recordings: [], total: 0, nextOffset: null };
1559
+ }
1560
+ return store.list(user.name, msg.offset, msg.limit);
1561
+ case 'get':
1562
+ if (!user)
1563
+ throw new BrokerError('not_found', 'Browser recording not found');
1564
+ return store.get(user.name, msg.recordingId);
1565
+ case 'steps':
1566
+ if (!user)
1567
+ throw new BrokerError('not_found', 'Browser recording not found');
1568
+ return store.steps(user.name, msg.recordingId, msg.offset, msg.limit);
1569
+ case 'snapshot':
1570
+ if (!user)
1571
+ throw new BrokerError('not_found', 'Browser recording not found');
1572
+ return store.snapshot(user.name, msg.recordingId, msg.snapshotId);
1573
+ default:
1574
+ throw new BrokerError('invalid_args', 'Unknown recording read');
1575
+ }
1576
+ }
1577
+
1578
+ recordingFiles(msg) {
1579
+ const user = this.#userOf(msg.sessionId);
1580
+ if (!user)
1581
+ throw new BrokerError('not_found', 'Browser recording not found');
1582
+ return { files: this.deps.store.files(user.name, msg.recordingId) };
1583
+ }
1584
+
1585
+ async downloadList(msg) {
1586
+ const user = this.#userOf(msg.sessionId);
1587
+ return {
1588
+ downloads: user ? await this.deps.transfers.listDownloads(user) : []
1589
+ };
1590
+ }
1591
+
1592
+ async downloadPath(msg) {
1593
+ const user = this.#userOf(msg.sessionId);
1594
+ if (!user) throw new BrokerError('not_found', 'Download not found');
1595
+ return this.deps.transfers.stageDownload(user, msg.downloadId);
1596
+ }
1597
+
1598
+ /**
1599
+ * v3 `cred_revoke`: drop the credential proxy's cached values and host
1600
+ * maps for one session, one proxy token, or (sessionId null) all of them.
1601
+ */
1602
+ credRevoke(msg) {
1603
+ const sessionId =
1604
+ typeof msg.sessionId === 'string' && msg.sessionId ? msg.sessionId : null;
1605
+ if (msg.sessionId !== null && sessionId === null)
1606
+ throw new BrokerError(
1607
+ 'invalid_args',
1608
+ 'sessionId must be a string or null'
1609
+ );
1610
+ if (msg.token !== undefined && typeof msg.token !== 'string')
1611
+ throw new BrokerError('invalid_args', 'token must be a string');
1612
+ const proxy = this.deps.credProxy;
1613
+ if (!proxy) return { revoked: 0 };
1614
+ return { revoked: proxy.revoke({ sessionId, token: msg.token }) };
1615
+ }
1616
+
1617
+ async handleRequest(msg) {
1618
+ if (msg.t === 'cred_revoke') return this.credRevoke(msg);
1619
+ if (
1620
+ msg.t !== 'state' &&
1621
+ (typeof msg.sessionId !== 'string' || !msg.sessionId)
1622
+ ) {
1623
+ throw new BrokerError('invalid_args', 'sessionId is required');
1624
+ }
1625
+ switch (msg.t) {
1626
+ case 'open':
1627
+ return this.open(msg);
1628
+ case 'close':
1629
+ return this.close(msg);
1630
+ case 'state':
1631
+ return this.state(msg);
1632
+ case 'control':
1633
+ return this.#require(msg.sessionId).control(msg);
1634
+ case 'command':
1635
+ return this.#require(msg.sessionId).command(msg);
1636
+ case 'recording_start':
1637
+ return this.#require(msg.sessionId).recordingStart(msg);
1638
+ case 'recording_stop':
1639
+ return this.#require(msg.sessionId).recordingStop(msg);
1640
+ case 'recording_read':
1641
+ return this.recordingRead(msg);
1642
+ case 'recording_files':
1643
+ return this.recordingFiles(msg);
1644
+ case 'download_list':
1645
+ return this.downloadList(msg);
1646
+ case 'download_path':
1647
+ return this.downloadPath(msg);
1648
+ case 'upload_begin':
1649
+ return this.#require(msg.sessionId).uploadBegin(msg);
1650
+ case 'upload_commit':
1651
+ return this.#require(msg.sessionId).uploadCommit(msg);
1652
+ case 'file_chooser_cancel':
1653
+ return this.#require(msg.sessionId).fileChooserCancel(msg);
1654
+ default:
1655
+ throw new BrokerError('invalid_args', 'Unknown request');
1656
+ }
1657
+ }
1658
+
1659
+ handlePush(msg) {
1660
+ if (msg.t === 'input') {
1661
+ const browser = this.#browsers.get(msg.sessionId);
1662
+ if (!browser) {
1663
+ this.deps.emit(msg.sessionId, 'input_rejected', {
1664
+ seq: msg.seq ?? null,
1665
+ code: 'no_browser',
1666
+ message: 'No browser is open for this chat.'
1667
+ });
1668
+ return;
1669
+ }
1670
+ browser.input(msg);
1671
+ } else if (msg.t === 'screencast') {
1672
+ const browser = this.#browsers.get(msg.sessionId);
1673
+ browser
1674
+ ?.setScreencast(msg.on, msg.profile)
1675
+ .catch((error) =>
1676
+ log.warn('screencast failed', { error: errorText(error) })
1677
+ );
1678
+ }
1679
+ }
1680
+
1681
+ /** The relay dropped: nobody can be watching, and viewer connections are gone. */
1682
+ async relayLost() {
1683
+ await Promise.all(
1684
+ [...this.#browsers.values()].map(async (b) => {
1685
+ await b.setScreencast(false).catch(() => undefined);
1686
+ await b.relayLost().catch(() => undefined);
1687
+ })
1688
+ );
1689
+ }
1690
+
1691
+ async shutdown() {
1692
+ for (const browser of this.#browsers.values()) {
1693
+ if (browser.recorder.recording)
1694
+ browser.recorder.interrupt(GAP.appStopped);
1695
+ }
1696
+ await Promise.all([...this.#browsers.values()].map((b) => b.close()));
1697
+ this.#browsers.clear();
1698
+ }
1699
+ }