ai-agentmanager 0.0.0-stage → 1.0.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 (58) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +4 -0
  3. package/README.md +767 -2
  4. package/SECURITY.md +44 -0
  5. package/bin/agentmgr-hub.js +16 -0
  6. package/bin/agentmgr.js +4 -0
  7. package/docs/architecture.md +67 -0
  8. package/docs/distributed.md +147 -0
  9. package/docs/engines.md +177 -0
  10. package/docs/images/agents.jpg +0 -0
  11. package/docs/images/conflict-radar.jpg +0 -0
  12. package/docs/plugins.md +81 -0
  13. package/package.json +56 -4
  14. package/public/app.js +3083 -0
  15. package/public/hub/hub.css +230 -0
  16. package/public/hub/hub.js +766 -0
  17. package/public/hub/index.html +146 -0
  18. package/public/hub/term.js +147 -0
  19. package/public/index.html +342 -0
  20. package/public/share.html +34 -0
  21. package/public/share.js +41 -0
  22. package/public/style.css +541 -0
  23. package/public/touchscroll.js +73 -0
  24. package/public/transport.js +78 -0
  25. package/scripts/build-release.sh +58 -0
  26. package/scripts/fix-pty.js +15 -0
  27. package/src/backlog.js +413 -0
  28. package/src/brief.js +512 -0
  29. package/src/cli.js +1447 -0
  30. package/src/client.js +49 -0
  31. package/src/config.js +109 -0
  32. package/src/conflicts.js +105 -0
  33. package/src/engines/antigravity.js +296 -0
  34. package/src/engines/claude.js +98 -0
  35. package/src/engines/codex.js +331 -0
  36. package/src/engines/index.js +37 -0
  37. package/src/fleet.js +176 -0
  38. package/src/git.js +340 -0
  39. package/src/hub.js +857 -0
  40. package/src/hubactions.js +107 -0
  41. package/src/hubbacklog.js +373 -0
  42. package/src/hublink.js +437 -0
  43. package/src/inbox.js +94 -0
  44. package/src/judge.js +278 -0
  45. package/src/livebrowser.js +637 -0
  46. package/src/manager.js +2554 -0
  47. package/src/notify.js +284 -0
  48. package/src/plugins.js +119 -0
  49. package/src/preview.js +334 -0
  50. package/src/races.js +192 -0
  51. package/src/remote.js +284 -0
  52. package/src/server.js +759 -0
  53. package/src/service.js +150 -0
  54. package/src/sessions.js +160 -0
  55. package/src/store.js +104 -0
  56. package/src/stuck.js +160 -0
  57. package/src/tracker.js +311 -0
  58. package/src/trust.js +44 -0
@@ -0,0 +1,637 @@
1
+ // Live browser tabs: a real Chrome on this machine, streamed into the Browser tab.
2
+ // Chrome runs headless with its own profile (~/.agentmanager/browser-profile), so sign-ins are
3
+ // remembered. Each browser tab is one Chrome page; its screen is streamed as JPEG frames
4
+ // (Page.startScreencast) to the people viewing it, and their mouse, keys and text are replayed
5
+ // into it. Because the page runs here, `localhost` means this machine and a CLI's sign-in
6
+ // callback (http://127.0.0.1:PORT/...) reaches the CLI waiting here, from any device.
7
+ // Popups (window.open, target=_blank) open as new tabs of the same agent.
8
+ // Chrome starts on the first view and stops after a while with nobody watching.
9
+ import { execFileSync, spawn } from 'node:child_process';
10
+ import { EventEmitter } from 'node:events';
11
+ import fs from 'node:fs';
12
+ import os from 'node:os';
13
+ import path from 'node:path';
14
+ import WebSocket from 'ws';
15
+ import { paths } from './config.js';
16
+
17
+ const IDLE_MS = 15 * 60_000;
18
+ const CANDIDATES = {
19
+ darwin: [
20
+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
21
+ '/Applications/Chromium.app/Contents/MacOS/Chromium',
22
+ '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
23
+ '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
24
+ ],
25
+ linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
26
+ win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'],
27
+ };
28
+
29
+ /** The Chrome-family browser to run: config `browserBin`, else the first one installed. */
30
+ export function findBrowser(config = {}) {
31
+ if (config.browserBin) return fs.existsSync(config.browserBin) ? config.browserBin : null;
32
+ return (CANDIDATES[process.platform] ?? []).find((p) => fs.existsSync(p)) ?? null;
33
+ }
34
+
35
+ /** Minimal Chrome DevTools Protocol client over one WebSocket (flattened sessions). */
36
+ class Cdp extends EventEmitter {
37
+ constructor(url) {
38
+ super();
39
+ this.ws = new WebSocket(url, { perMessageDeflate: false, maxPayload: 256 * 1024 * 1024 });
40
+ this.id = 0;
41
+ this.pending = new Map();
42
+ this.ready = new Promise((resolve, reject) => {
43
+ this.ws.once('open', resolve);
44
+ this.ws.once('error', reject);
45
+ });
46
+ this.ws.on('message', (raw) => {
47
+ const msg = JSON.parse(raw.toString());
48
+ if (msg.id) {
49
+ const p = this.pending.get(msg.id);
50
+ this.pending.delete(msg.id);
51
+ if (msg.error) p?.reject(new Error(msg.error.message));
52
+ else p?.resolve(msg.result);
53
+ } else this.emit('event', msg);
54
+ });
55
+ this.ws.on('close', () => {
56
+ for (const p of this.pending.values()) p.reject(new Error('browser closed'));
57
+ this.pending.clear();
58
+ this.emit('close');
59
+ });
60
+ }
61
+
62
+ send(method, params = {}, sessionId) {
63
+ if (this.ws.readyState !== WebSocket.OPEN) return Promise.reject(new Error('browser closed'));
64
+ const id = ++this.id;
65
+ this.ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
66
+ return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
67
+ }
68
+
69
+ close() {
70
+ this.ws.close();
71
+ }
72
+ }
73
+
74
+ // Sound: in each page and frame (in a world of our own the page can't see), the sound of
75
+ // any <video> or <audio> that plays is routed into a silent graph and sent here as 16-bit PCM,
76
+ // 24 kHz stereo, about 170 ms at a time. Chrome itself stays muted. Media loaded from another
77
+ // site without CORS can't be read this way and stays silent.
78
+ export const AUDIO_RATE = 24000;
79
+ const AUDIO_WORLD = 'agentmgr-audio';
80
+ const AUDIO_BINDING = '__agentmgrAudio';
81
+ const AUDIO_SCRIPT = `(() => {
82
+ if (globalThis.__agentmgrHooked) return;
83
+ globalThis.__agentmgrHooked = true;
84
+ let ctx, node;
85
+ const ensure = () => {
86
+ if (ctx) return true;
87
+ try {
88
+ ctx = new AudioContext({ sampleRate: ${AUDIO_RATE} });
89
+ node = ctx.createScriptProcessor(4096, 2, 2);
90
+ const sink = ctx.createGain();
91
+ sink.gain.value = 0;
92
+ node.connect(sink);
93
+ sink.connect(ctx.destination);
94
+ node.onaudioprocess = (e) => {
95
+ const l = e.inputBuffer.getChannelData(0);
96
+ const r = e.inputBuffer.numberOfChannels > 1 ? e.inputBuffer.getChannelData(1) : l;
97
+ let sound = false;
98
+ for (let i = 0; i < l.length; i += 32) if (l[i] || r[i]) { sound = true; break; }
99
+ if (!sound) return;
100
+ const pcm = new Int16Array(l.length * 2);
101
+ for (let i = 0; i < l.length; i++) {
102
+ pcm[2 * i] = Math.max(-1, Math.min(1, l[i])) * 32767;
103
+ pcm[2 * i + 1] = Math.max(-1, Math.min(1, r[i])) * 32767;
104
+ }
105
+ const b = new Uint8Array(pcm.buffer);
106
+ let s = '';
107
+ for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode.apply(null, b.subarray(i, i + 0x8000));
108
+ globalThis.${AUDIO_BINDING}(btoa(s));
109
+ };
110
+ return true;
111
+ } catch { return false; }
112
+ };
113
+ const hook = (el) => {
114
+ if (!(el instanceof HTMLMediaElement) || el.__agentmgrHooked || !ensure()) return;
115
+ try {
116
+ ctx.createMediaElementSource(el).connect(node);
117
+ el.__agentmgrHooked = true;
118
+ } catch {}
119
+ ctx.resume();
120
+ };
121
+ document.addEventListener('play', (e) => hook(e.target), true);
122
+ for (const el of document.querySelectorAll('video, audio')) if (!el.paused) hook(el);
123
+ })();`;
124
+
125
+ // Keys that aren't text: what Chrome needs to act on them.
126
+ const KEYS = {
127
+ Enter: { code: 'Enter', keyCode: 13, text: '\r' },
128
+ Backspace: { code: 'Backspace', keyCode: 8 },
129
+ Tab: { code: 'Tab', keyCode: 9 },
130
+ Escape: { code: 'Escape', keyCode: 27 },
131
+ Delete: { code: 'Delete', keyCode: 46 },
132
+ ArrowLeft: { code: 'ArrowLeft', keyCode: 37 },
133
+ ArrowUp: { code: 'ArrowUp', keyCode: 38 },
134
+ ArrowRight: { code: 'ArrowRight', keyCode: 39 },
135
+ ArrowDown: { code: 'ArrowDown', keyCode: 40 },
136
+ Home: { code: 'Home', keyCode: 36 },
137
+ End: { code: 'End', keyCode: 35 },
138
+ PageUp: { code: 'PageUp', keyCode: 33 },
139
+ PageDown: { code: 'PageDown', keyCode: 34 },
140
+ };
141
+
142
+ export class LiveBrowser extends EventEmitter {
143
+ /**
144
+ * onNavigate(agentId, n, url): a tab went somewhere (saved as the tab's address).
145
+ * onPopup(agentId, url) => n: a page opened a new window; returns the new tab's number.
146
+ * onClosed(agentId, n): a page closed itself (e.g. a sign-in popup when it is done).
147
+ */
148
+ constructor({ config, onNavigate, onPopup, onClosed }) {
149
+ super();
150
+ this.config = config;
151
+ this.onNavigate = onNavigate;
152
+ this.onPopup = onPopup;
153
+ this.onClosed = onClosed;
154
+ this.tabs = new Map(); // `${agentId}:${n}` -> tab
155
+ this.byTarget = new Map(); // targetId -> tab
156
+ this.bySession = new Map(); // sessionId -> tab
157
+ this.frameSessions = new Map(); // sessionId of a cross-site frame inside a tab -> tab (for its sound)
158
+ this.starting = null;
159
+ this.idleTimer = setInterval(() => this.reapIdle(), 60_000);
160
+ this.idleTimer.unref();
161
+ }
162
+
163
+ available() {
164
+ return Boolean(findBrowser(this.config));
165
+ }
166
+
167
+ status() {
168
+ return { available: this.available(), running: Boolean(this.cdp), tabs: this.tabs.size };
169
+ }
170
+
171
+ // ------------------------------------------------------------ Chrome itself
172
+
173
+ /** A Chrome left from a daemon that crashed still holds the profile: stop it (only that one). */
174
+ clearStale(profile) {
175
+ try {
176
+ const pid = Number(fs.readlinkSync(path.join(profile, 'SingletonLock')).split('-').pop());
177
+ if (!pid) return;
178
+ const cmd = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
179
+ if (cmd.includes(`--user-data-dir=${profile}`)) process.kill(pid);
180
+ } catch {}
181
+ }
182
+
183
+ start() {
184
+ if (this.cdp) return Promise.resolve(this.cdp);
185
+ if (this.starting) return this.starting;
186
+ const bin = findBrowser(this.config);
187
+ if (!bin) return Promise.reject(Object.assign(new Error('No Chrome, Chromium, Brave or Edge found on this machine (set "browserBin" in config.json)'), { status: 501 }));
188
+ this.starting = new Promise((resolve, reject) => {
189
+ const profile = path.join(paths.home, 'browser-profile');
190
+ fs.mkdirSync(profile, { recursive: true });
191
+ this.clearStale(profile);
192
+ const proc = spawn(
193
+ bin,
194
+ [
195
+ ...(this.config.browserHeadless === false ? ['--window-position=0,0'] : ['--headless=new']),
196
+ '--remote-debugging-port=0',
197
+ '--remote-debugging-address=127.0.0.1',
198
+ `--user-data-dir=${profile}`,
199
+ '--no-first-run',
200
+ '--no-default-browser-check',
201
+ '--disable-features=Translate,MediaRouter',
202
+ // Without this, navigator.webdriver is true and sites treat every page as a bot.
203
+ '--disable-blink-features=AutomationControlled',
204
+ '--mute-audio',
205
+ // Videos may start without a click; the sound is captured from the page, not played here.
206
+ '--autoplay-policy=no-user-gesture-required',
207
+ '--hide-scrollbars',
208
+ '--window-size=1280,800',
209
+ // Only when asked: in containers and on Linux that blocks user namespaces, Chrome's
210
+ // sandbox can't start. Without it, a page that exploits Chrome runs as you.
211
+ ...(this.config.browserNoSandbox ? ['--no-sandbox'] : []),
212
+ 'about:blank',
213
+ ],
214
+ { stdio: ['ignore', 'ignore', 'pipe'] },
215
+ );
216
+ let err = '';
217
+ let connecting = false;
218
+ const fail = (e) => {
219
+ this.starting = null;
220
+ reject(e);
221
+ };
222
+ const timer = setTimeout(() => {
223
+ proc.kill();
224
+ fail(new Error(`Chrome did not start: ${err.slice(-300)}`));
225
+ }, 20_000);
226
+ proc.stderr.on('data', async (d) => {
227
+ err += d;
228
+ const m = err.match(/DevTools listening on (ws:\/\/\S+)/);
229
+ if (!m || connecting) return;
230
+ connecting = true; // stderr keeps coming; connect once
231
+ clearTimeout(timer);
232
+ try {
233
+ const cdp = new Cdp(m[1]);
234
+ await cdp.ready;
235
+ this.proc = proc;
236
+ this.cdp = cdp;
237
+ cdp.on('event', (msg) => this.onEvent(msg));
238
+ cdp.on('close', () => this.stopped());
239
+ const { userAgent, product } = await cdp.send('Browser.getVersion');
240
+ // Headless Chrome says so in its user agent and its client hints (Sec-CH-UA); sites
241
+ // like Google then treat it as a bot. Present it as the regular browser it is.
242
+ this.userAgent = userAgent.replace('HeadlessChrome', 'Chrome');
243
+ const full = (product.split('/')[1] ?? '0').trim();
244
+ const major = full.split('.')[0];
245
+ const brand = /Brave/.test(bin) ? 'Brave' : /Edge/.test(bin) ? 'Microsoft Edge' : /Chromium/.test(bin) ? 'Chromium' : 'Google Chrome';
246
+ const brands = [{ brand: 'Not)A;Brand', version: '8' }, { brand: 'Chromium', version: major }, ...(brand === 'Chromium' ? [] : [{ brand, version: major }])];
247
+ this.userAgentMetadata = {
248
+ brands,
249
+ fullVersionList: brands.map((b) => ({ ...b, version: b.brand.startsWith('Not') ? '8.0.0.0' : full })),
250
+ fullVersion: full,
251
+ platform: { darwin: 'macOS', win32: 'Windows', linux: 'Linux' }[process.platform] ?? 'Unknown',
252
+ platformVersion: process.platform === 'darwin' ? '15.0.0' : '',
253
+ architecture: process.arch === 'arm64' ? 'arm' : 'x86',
254
+ bitness: '64',
255
+ model: '',
256
+ mobile: false,
257
+ };
258
+ this.downloads = path.join(os.homedir(), 'Downloads', 'agentmanager');
259
+ fs.mkdirSync(this.downloads, { recursive: true });
260
+ await cdp.send('Browser.setDownloadBehavior', { behavior: 'allowAndName', downloadPath: this.downloads, eventsEnabled: true }).catch(() => {});
261
+ await cdp.send('Target.setDiscoverTargets', { discover: true });
262
+ this.starting = null;
263
+ resolve(cdp);
264
+ } catch (e) {
265
+ proc.kill();
266
+ fail(e);
267
+ }
268
+ });
269
+ proc.on('exit', () => {
270
+ clearTimeout(timer);
271
+ if (this.cdp) return;
272
+ if (/No usable sandbox/i.test(err)) {
273
+ return fail(
274
+ Object.assign(
275
+ new Error(
276
+ 'Chrome cannot start its sandbox on this machine (common in containers and on Ubuntu 23.10+, which restricts user namespaces). Fix the system (see https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md), or set "browserNoSandbox": true in config.json if you accept that a malicious page could then run as you.',
277
+ ),
278
+ { status: 501 },
279
+ ),
280
+ );
281
+ }
282
+ fail(new Error(`Chrome exited: ${err.slice(-300)}`));
283
+ });
284
+ });
285
+ return this.starting;
286
+ }
287
+
288
+ stopped() {
289
+ this.cdp = null;
290
+ this.proc = null;
291
+ for (const tab of this.tabs.values()) {
292
+ tab.sessionId = null;
293
+ tab.targetId = null;
294
+ this.push(tab, { t: 'closed' });
295
+ }
296
+ this.byTarget.clear();
297
+ this.bySession.clear();
298
+ }
299
+
300
+ stop() {
301
+ this.cdp?.close();
302
+ this.proc?.kill();
303
+ this.stopped();
304
+ }
305
+
306
+ /** Nobody watching any tab for a while: let Chrome go (tabs reopen at their address). */
307
+ reapIdle() {
308
+ if (!this.cdp) return;
309
+ const watched = [...this.tabs.values()].some((t) => t.clients.size || Date.now() - t.lastSeen < IDLE_MS);
310
+ if (!watched) {
311
+ this.stop();
312
+ this.tabs.clear();
313
+ }
314
+ }
315
+
316
+ // ------------------------------------------------------------------- tabs
317
+
318
+ key(agentId, n) {
319
+ return `${agentId}:${n}`;
320
+ }
321
+
322
+ /** The tab's Chrome page, created (at `url`) if it isn't open yet. */
323
+ async ensure(agentId, n, url, viewport) {
324
+ const cdp = await this.start();
325
+ const k = this.key(agentId, n);
326
+ let tab = this.tabs.get(k);
327
+ if (tab?.sessionId) return tab;
328
+ tab ??= { agentId, n, url, title: '', clients: new Set(), lastSeen: Date.now(), viewport: this.fit(viewport), frame: null, casting: false };
329
+ this.tabs.set(k, tab);
330
+ if (!tab.targetId) {
331
+ const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
332
+ tab.targetId = targetId;
333
+ }
334
+ this.byTarget.set(tab.targetId, tab);
335
+ await this.attach(tab);
336
+ if (url && url !== 'about:blank') await cdp.send('Page.navigate', { url }, tab.sessionId).catch(() => {});
337
+ return tab;
338
+ }
339
+
340
+ async attach(tab) {
341
+ const cdp = this.cdp;
342
+ const { sessionId } = await cdp.send('Target.attachToTarget', { targetId: tab.targetId, flatten: true });
343
+ tab.sessionId = sessionId;
344
+ this.bySession.set(sessionId, tab);
345
+ await Promise.all([
346
+ cdp.send('Page.enable', {}, sessionId),
347
+ cdp.send('Runtime.enable', {}, sessionId),
348
+ cdp.send('Network.setUserAgentOverride', { userAgent: this.userAgent, userAgentMetadata: this.userAgentMetadata }, sessionId),
349
+ this.applyViewport(tab),
350
+ this.hookAudio(sessionId),
351
+ // Frames from other sites run as targets of their own; attach to them for their sound.
352
+ cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true }, sessionId),
353
+ ]).catch(() => {});
354
+ if (tab.clients.size) await this.cast(tab, true);
355
+ await this.refresh(tab);
356
+ }
357
+
358
+ /** Current address and title from Chrome (a popup may have moved on before we attached). */
359
+ async refresh(tab) {
360
+ const info = await this.cdp?.send('Target.getTargetInfo', { targetId: tab.targetId }).catch(() => null);
361
+ if (!info) return;
362
+ const { url, title } = info.targetInfo;
363
+ if (title && title !== tab.title) {
364
+ tab.title = title;
365
+ this.push(tab, { t: 'state', url: tab.url, title });
366
+ }
367
+ this.navigated(tab, url);
368
+ }
369
+
370
+ async hookAudio(sessionId) {
371
+ await this.cdp.send('Runtime.addBinding', { name: AUDIO_BINDING, executionContextName: AUDIO_WORLD }, sessionId);
372
+ await this.cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: AUDIO_SCRIPT, worldName: AUDIO_WORLD, runImmediately: true }, sessionId);
373
+ }
374
+
375
+ async applyViewport(tab) {
376
+ const { width, height, mobile, scale = 1 } = tab.viewport;
377
+ await this.cdp?.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: scale, mobile }, tab.sessionId);
378
+ if (tab.casting) await this.cast(tab, true);
379
+ }
380
+
381
+ async cast(tab, on) {
382
+ if (!this.cdp || !tab.sessionId) return;
383
+ if (tab.casting) await this.cdp.send('Page.stopScreencast', {}, tab.sessionId).catch(() => {});
384
+ tab.casting = false;
385
+ clearTimeout(tab.castRetry);
386
+ if (!on) return;
387
+ const scale = tab.viewport.scale ?? 1;
388
+ try {
389
+ await this.cdp.send(
390
+ 'Page.startScreencast',
391
+ { format: 'jpeg', quality: 65, maxWidth: Math.round(tab.viewport.width * scale), maxHeight: Math.round(tab.viewport.height * scale), everyNthFrame: 1 },
392
+ tab.sessionId,
393
+ );
394
+ tab.casting = true;
395
+ } catch {
396
+ // Mid-navigation (Chrome swapping the page's process): try again shortly.
397
+ tab.castRetry = setTimeout(() => tab.clients.size && this.cast(tab, true).catch(() => {}), 300);
398
+ }
399
+ }
400
+
401
+ /** Someone opened the tab: stream it to them. Returns detach(). */
402
+ async view(agentId, n, url, client, viewport) {
403
+ const tab = await this.ensure(agentId, n, url, viewport);
404
+ if (viewport) await this.resize(agentId, n, viewport).catch(() => {});
405
+ tab.clients.add(client);
406
+ tab.lastSeen = Date.now();
407
+ client.send({ t: 'state', url: tab.url, title: tab.title, viewport: tab.viewport });
408
+ if (tab.frame) client.send(tab.frame);
409
+ // Restart the stream so the newcomer gets a fresh frame (Chrome only sends on changes).
410
+ await this.cast(tab, true).catch(() => {});
411
+ return () => {
412
+ tab.clients.delete(client);
413
+ tab.lastSeen = Date.now();
414
+ if (!tab.clients.size) this.cast(tab, false).catch(() => {});
415
+ };
416
+ }
417
+
418
+ push(tab, msg) {
419
+ for (const c of tab.clients) c.send(msg);
420
+ }
421
+
422
+ async close(agentId, n) {
423
+ const tab = this.tabs.get(this.key(agentId, n));
424
+ if (!tab) return;
425
+ this.tabs.delete(this.key(agentId, n));
426
+ this.push(tab, { t: 'closed' });
427
+ if (tab.targetId) {
428
+ this.byTarget.delete(tab.targetId);
429
+ this.bySession.delete(tab.sessionId);
430
+ await this.cdp?.send('Target.closeTarget', { targetId: tab.targetId }).catch(() => {});
431
+ }
432
+ }
433
+
434
+ async closeAgent(agentId) {
435
+ for (const tab of [...this.tabs.values()]) if (tab.agentId === agentId) await this.close(agentId, tab.n);
436
+ }
437
+
438
+ // ---------------------------------------------------------------- control
439
+
440
+ tab(agentId, n) {
441
+ const tab = this.tabs.get(this.key(agentId, n));
442
+ if (!tab?.sessionId) throw Object.assign(new Error('That browser tab is not open'), { status: 409 });
443
+ tab.lastSeen = Date.now();
444
+ return tab;
445
+ }
446
+
447
+ async navigate(agentId, n, url) {
448
+ const tab = await this.ensure(agentId, n, url);
449
+ await this.cdp.send('Page.navigate', { url }, tab.sessionId);
450
+ }
451
+
452
+ async go(agentId, n, where) {
453
+ const tab = this.tab(agentId, n);
454
+ const s = tab.sessionId;
455
+ if (where === 'reload') return this.cdp.send('Page.reload', {}, s);
456
+ const { currentIndex, entries } = await this.cdp.send('Page.getNavigationHistory', {}, s);
457
+ const entry = entries[currentIndex + (where === 'back' ? -1 : 1)];
458
+ if (entry) await this.cdp.send('Page.navigateToHistoryEntry', { entryId: entry.id }, s);
459
+ }
460
+
461
+ /** A viewer's size, within sane bounds. */
462
+ fit({ width, height, mobile, scale } = {}) {
463
+ const w = Math.max(240, Math.min(2560, Math.round(Number(width) || 1280)));
464
+ const h = Math.max(200, Math.min(2000, Math.round(Number(height) || 800)));
465
+ return {
466
+ width: w,
467
+ height: h,
468
+ mobile: mobile === true || mobile === '1' || mobile === 'true',
469
+ // Render at the viewer's pixel density (a phone is 3x) for sharp text, within a budget of
470
+ // about 2.4 million pixels per frame so a big desktop window stays light.
471
+ scale: Math.round(10 * Math.max(1, Math.min(Number(scale) || 1, 3, Math.sqrt(2_400_000 / (w * h))))) / 10,
472
+ };
473
+ }
474
+
475
+ async resize(agentId, n, size) {
476
+ const tab = this.tab(agentId, n);
477
+ const next = this.fit(size);
478
+ if (JSON.stringify(next) === JSON.stringify(tab.viewport)) return;
479
+ tab.viewport = next;
480
+ tab.frame = null; // the old size; a fresh frame follows
481
+ await this.applyViewport(tab);
482
+ }
483
+
484
+ /**
485
+ * Replay what the person did, in order. Events (in page CSS pixels):
486
+ * { type: 'mouse', action: 'down'|'up'|'move', x, y, button, clicks, modifiers }
487
+ * { type: 'wheel', x, y, dx, dy }
488
+ * { type: 'key', key, modifiers } a non-text key (Enter, Backspace, arrows...) or a shortcut
489
+ * { type: 'text', text } typed or pasted text
490
+ */
491
+ async input(agentId, n, events) {
492
+ await this.replay(agentId, n, events);
493
+ // After a click, say whether it landed in a text field (a phone then shows its keyboard).
494
+ const last = Array.isArray(events) ? events.at(-1) : null;
495
+ if (last?.type !== 'mouse' || last.action !== 'up') return {};
496
+ const tab = this.tab(agentId, n);
497
+ const r = await this.cdp
498
+ .send('Runtime.evaluate', { expression: "(() => { const a = document.activeElement; return !!a && (a.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(a.tagName)); })()", returnByValue: true }, tab.sessionId)
499
+ .catch(() => null);
500
+ return { editable: Boolean(r?.result?.value) };
501
+ }
502
+
503
+ async replay(agentId, n, events) {
504
+ const tab = this.tab(agentId, n);
505
+ const s = tab.sessionId;
506
+ const send = (m, p) => this.cdp.send(m, p, s);
507
+ for (const e of (Array.isArray(events) ? events : []).slice(0, 200)) {
508
+ const modifiers = Number(e.modifiers) || 0;
509
+ if (e.type === 'mouse') {
510
+ const type = { down: 'mousePressed', up: 'mouseReleased', move: 'mouseMoved' }[e.action];
511
+ if (!type) continue;
512
+ await send('Input.dispatchMouseEvent', { type, x: Number(e.x) || 0, y: Number(e.y) || 0, button: e.action === 'move' ? (e.button ?? 'none') : (e.button ?? 'left'), buttons: e.buttons ?? 0, clickCount: Number(e.clicks) || (e.action === 'move' ? 0 : 1), modifiers });
513
+ } else if (e.type === 'wheel') {
514
+ await send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: Number(e.x) || 0, y: Number(e.y) || 0, deltaX: Number(e.dx) || 0, deltaY: Number(e.dy) || 0, modifiers });
515
+ } else if (e.type === 'char') {
516
+ // One typed character as a real key press (keydown, keypress, input), which sites
517
+ // listening for keys need; insertText alone only fires input.
518
+ const text = String(e.text ?? '').slice(0, 2);
519
+ if (!text) continue;
520
+ const code = /^[a-z]$/i.test(text) ? `Key${text.toUpperCase()}` : /^\d$/.test(text) ? `Digit${text}` : text === ' ' ? 'Space' : '';
521
+ const keyCode = /^[a-z\d ]$/i.test(text) ? text.toUpperCase().charCodeAt(0) : 0;
522
+ const base = { key: text, code, windowsVirtualKeyCode: keyCode, nativeVirtualKeyCode: keyCode, modifiers };
523
+ await send('Input.dispatchKeyEvent', { type: 'keyDown', ...base, text, unmodifiedText: text });
524
+ await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
525
+ } else if (e.type === 'text') {
526
+ const text = String(e.text ?? '').slice(0, 20_000);
527
+ if (text) await send('Input.insertText', { text });
528
+ } else if (e.type === 'key') {
529
+ const key = String(e.key ?? '');
530
+ const k = KEYS[key];
531
+ const single = key.length === 1;
532
+ const code = k?.code ?? (single ? (/[a-z]/i.test(key) ? `Key${key.toUpperCase()}` : /\d/.test(key) ? `Digit${key}` : '') : '');
533
+ const keyCode = k?.keyCode ?? (single ? key.toUpperCase().charCodeAt(0) : 0);
534
+ // A shortcut (Ctrl/Cmd+A, C, V, X, Z) is passed to Chrome as an editing command too.
535
+ const commands = modifiers & (2 | 4) && single ? { a: ['selectAll'], c: ['copy'], x: ['cut'], v: ['paste'], z: [modifiers & 8 ? 'redo' : 'undo'] }[key.toLowerCase()] : undefined;
536
+ const base = { key, code, windowsVirtualKeyCode: keyCode, nativeVirtualKeyCode: keyCode, modifiers };
537
+ await send('Input.dispatchKeyEvent', { type: k?.text ? 'keyDown' : 'rawKeyDown', ...base, ...(k?.text ? { text: k.text } : {}), ...(commands ? { commands } : {}) });
538
+ await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
539
+ }
540
+ }
541
+ }
542
+
543
+ /** What is selected in the page, for copying to the person's clipboard. */
544
+ async selection(agentId, n) {
545
+ const tab = this.tab(agentId, n);
546
+ const r = await this.cdp.send('Runtime.evaluate', { expression: 'String(getSelection())', returnByValue: true }, tab.sessionId);
547
+ return { text: String(r.result?.value ?? '').slice(0, 100_000) };
548
+ }
549
+
550
+ // ----------------------------------------------------------------- events
551
+
552
+ onEvent({ method, params, sessionId }) {
553
+ const tab = sessionId ? this.bySession.get(sessionId) : null;
554
+ if (method === 'Page.screencastFrame' && tab) {
555
+ this.cdp.send('Page.screencastFrameAck', { sessionId: params.sessionId }, sessionId).catch(() => {});
556
+ // Taking the sharp screenshot makes Chrome repaint once; that frame shows nothing new.
557
+ if (Date.now() - (tab.sharpenedAt ?? 0) < 400) return;
558
+ const m = params.metadata;
559
+ tab.frame = { t: 'frame', d: params.data, w: m.deviceWidth, h: m.deviceHeight };
560
+ this.push(tab, tab.frame);
561
+ // Moving frames are compressed for speed; once the page holds still, send a sharp one.
562
+ clearTimeout(tab.sharpen);
563
+ tab.sharpen = setTimeout(() => this.sharpen(tab).catch(() => {}), 500);
564
+ } else if (method === 'Runtime.bindingCalled' && params.name === AUDIO_BINDING) {
565
+ const t = tab ?? this.frameSessions.get(sessionId);
566
+ if (t) for (const c of t.clients) if (c.audio) c.send({ t: 'audio', d: params.payload, rate: AUDIO_RATE });
567
+ } else if (method === 'Target.attachedToTarget' && sessionId && params.targetInfo.type === 'iframe') {
568
+ const t = tab ?? this.frameSessions.get(sessionId);
569
+ if (!t) return;
570
+ const child = params.sessionId;
571
+ this.frameSessions.set(child, t);
572
+ Promise.all([
573
+ this.cdp.send('Page.enable', {}, child),
574
+ this.hookAudio(child),
575
+ this.cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true }, child),
576
+ ]).catch(() => {});
577
+ } else if (method === 'Target.detachedFromTarget' && this.frameSessions.has(params.sessionId)) {
578
+ this.frameSessions.delete(params.sessionId);
579
+ } else if (method === 'Page.frameNavigated' && tab && !params.frame.parentId) {
580
+ this.navigated(tab, params.frame.url);
581
+ if (tab.clients.size && !tab.casting) this.cast(tab, true).catch(() => {});
582
+ } else if ((method === 'Page.loadEventFired' || method === 'Page.domContentEventFired') && tab) {
583
+ this.refresh(tab).catch(() => {});
584
+ } else if (method === 'Page.navigatedWithinDocument' && tab) {
585
+ this.navigated(tab, params.url);
586
+ } else if (method === 'Target.targetInfoChanged') {
587
+ const t = this.byTarget.get(params.targetInfo.targetId);
588
+ if (t && params.targetInfo.title !== t.title) {
589
+ t.title = params.targetInfo.title;
590
+ this.push(t, { t: 'state', url: t.url, title: t.title });
591
+ }
592
+ } else if (method === 'Target.targetCreated') {
593
+ this.popup(params.targetInfo).catch(() => {});
594
+ } else if (method === 'Target.targetDestroyed') {
595
+ const t = this.byTarget.get(params.targetId);
596
+ if (t && this.tabs.get(this.key(t.agentId, t.n)) === t) {
597
+ this.tabs.delete(this.key(t.agentId, t.n));
598
+ this.byTarget.delete(params.targetId);
599
+ this.push(t, { t: 'closed' });
600
+ this.onClosed?.(t.agentId, t.n);
601
+ }
602
+ } else if (method === 'Browser.downloadWillBegin') {
603
+ const t = this.byTarget.get(params.frameId) ?? [...this.tabs.values()].find((x) => x.clients.size);
604
+ if (t) this.push(t, { t: 'download', name: params.suggestedFilename, dir: this.downloads });
605
+ }
606
+ }
607
+
608
+ async sharpen(tab) {
609
+ if (!tab.clients.size || !tab.sessionId || !this.cdp) return;
610
+ tab.sharpenedAt = Date.now();
611
+ const { data } = await this.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 90 }, tab.sessionId);
612
+ tab.sharpenedAt = Date.now();
613
+ tab.frame = { t: 'frame', d: data, w: tab.viewport.width, h: tab.viewport.height, sharp: true };
614
+ this.push(tab, tab.frame);
615
+ }
616
+
617
+ navigated(tab, url) {
618
+ if (!url || url === tab.url || url.startsWith('about:') || url.startsWith('chrome-error:')) return;
619
+ tab.url = url;
620
+ this.push(tab, { t: 'state', url, title: tab.title });
621
+ this.onNavigate?.(tab.agentId, tab.n, url);
622
+ }
623
+
624
+ /** A page of ours opened a new window: it becomes a new tab of the same agent. */
625
+ async popup(info) {
626
+ if (info.type !== 'page' || !info.openerId || this.byTarget.has(info.targetId)) return;
627
+ const opener = this.byTarget.get(info.openerId);
628
+ if (!opener) return;
629
+ const n = await this.onPopup?.(opener.agentId, info.url || 'about:blank');
630
+ if (!n) return;
631
+ const tab = { agentId: opener.agentId, n, url: info.url, title: info.title, clients: new Set(), lastSeen: Date.now(), viewport: { ...opener.viewport }, frame: null, casting: false, targetId: info.targetId };
632
+ this.tabs.set(this.key(opener.agentId, n), tab);
633
+ this.byTarget.set(info.targetId, tab);
634
+ await this.attach(tab);
635
+ this.push(opener, { t: 'popup', n });
636
+ }
637
+ }