@revoengine/cli 1.0.29 → 1.0.31

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 (69) hide show
  1. package/README.md +156 -3
  2. package/dist/src/automation-contract.generated.d.ts +742 -0
  3. package/dist/src/automation-contract.generated.js +1021 -0
  4. package/dist/src/cli.js +9 -1
  5. package/dist/src/client.d.ts +24 -0
  6. package/dist/src/client.js +60 -0
  7. package/dist/src/commands/component.js +56 -23
  8. package/dist/src/commands/env.js +1 -1
  9. package/dist/src/commands/index.d.ts +2 -0
  10. package/dist/src/commands/index.js +2 -0
  11. package/dist/src/commands/studio.d.ts +3 -0
  12. package/dist/src/commands/studio.js +114 -0
  13. package/dist/src/commands/terminal-browser-human-input.d.ts +11 -0
  14. package/dist/src/commands/terminal-browser-human-input.js +44 -0
  15. package/dist/src/commands/terminal-browser-interaction.d.ts +25 -0
  16. package/dist/src/commands/terminal-browser-interaction.js +56 -0
  17. package/dist/src/commands/terminal-browser-live-protocol.d.ts +151 -0
  18. package/dist/src/commands/terminal-browser-live-protocol.js +177 -0
  19. package/dist/src/commands/terminal-browser-live-transport.d.ts +41 -0
  20. package/dist/src/commands/terminal-browser-live-transport.js +206 -0
  21. package/dist/src/commands/terminal-browser-live.d.ts +114 -0
  22. package/dist/src/commands/terminal-browser-live.js +455 -0
  23. package/dist/src/commands/terminal-browser-observation.d.ts +10 -0
  24. package/dist/src/commands/terminal-browser-observation.js +27 -0
  25. package/dist/src/commands/terminal-browser-page-input.d.ts +8 -0
  26. package/dist/src/commands/terminal-browser-page-input.js +94 -0
  27. package/dist/src/commands/terminal-browser-profile-preferences.d.ts +37 -0
  28. package/dist/src/commands/terminal-browser-profile-preferences.js +136 -0
  29. package/dist/src/commands/terminal-browser-profile.d.ts +52 -0
  30. package/dist/src/commands/terminal-browser-profile.js +447 -0
  31. package/dist/src/commands/terminal-browser.d.ts +28 -1
  32. package/dist/src/commands/terminal-browser.js +401 -55
  33. package/dist/src/commands/terminal-policy.js +2 -0
  34. package/dist/src/commands/terminal-public-web-proxy.d.ts +14 -0
  35. package/dist/src/commands/terminal-public-web-proxy.js +141 -0
  36. package/dist/src/commands/terminal-public-web.d.ts +11 -0
  37. package/dist/src/commands/terminal-public-web.js +99 -0
  38. package/dist/src/commands/terminal.d.ts +1 -0
  39. package/dist/src/commands/terminal.js +92 -9
  40. package/dist/src/commands/tests.d.ts +3 -0
  41. package/dist/src/commands/tests.js +236 -0
  42. package/dist/src/component-element-validation.d.ts +8 -0
  43. package/dist/src/component-element-validation.js +79 -0
  44. package/dist/src/component-lifecycle.d.ts +3 -0
  45. package/dist/src/component-lifecycle.js +17 -0
  46. package/dist/src/component-lock.d.ts +17 -12
  47. package/dist/src/component-lock.js +57 -6
  48. package/dist/src/component-manifests.js +3 -0
  49. package/dist/src/component-source-validation.d.ts +5 -0
  50. package/dist/src/component-source-validation.js +27 -0
  51. package/dist/src/env-sync.js +67 -9
  52. package/dist/src/native-tests.d.ts +61 -0
  53. package/dist/src/native-tests.js +20 -0
  54. package/dist/src/request-contract.d.ts +39 -0
  55. package/dist/src/request-contract.js +138 -0
  56. package/dist/src/resource-syncs/agent-sync.js +47 -7
  57. package/dist/src/resource-syncs/database-table-sync.js +8 -8
  58. package/dist/src/resource-syncs/endpoint-sync.js +20 -14
  59. package/dist/src/resource-syncs/group-sync.js +8 -3
  60. package/dist/src/resource-syncs/job-template-sync.js +75 -28
  61. package/dist/src/resource-syncs/role-group-sync.js +8 -0
  62. package/dist/src/resource-syncs/runtime-definition-validation.d.ts +14 -0
  63. package/dist/src/resource-syncs/runtime-definition-validation.js +153 -0
  64. package/dist/src/test-workspace.d.ts +33 -0
  65. package/dist/src/test-workspace.js +156 -0
  66. package/dist/src/types.d.ts +1 -0
  67. package/dist/src/ui.js +12 -0
  68. package/dist/src/update-notifier.d.ts +1 -1
  69. package/package.json +5 -3
@@ -0,0 +1,114 @@
1
+ import type { Page } from 'playwright-core';
2
+ import { BrowserObservations } from './terminal-browser-observation.ts';
3
+ import { type HumanInputScope } from './terminal-browser-human-input.ts';
4
+ import { type BrowserLiveControl, type BrowserLiveMode } from './terminal-browser-live-protocol.ts';
5
+ import type { BrowserProfileOwner, BrowserProfilePreferences } from './terminal-browser-profile-preferences.ts';
6
+ import type { SecureBrowserIdentity } from './terminal-secure-browser.ts';
7
+ export type BrowserLiveRecording = {
8
+ recordingId: string;
9
+ path: string;
10
+ size: number;
11
+ name: string;
12
+ mode: 'local' | 'storage' | 'both';
13
+ };
14
+ export type BrowserLiveOptions = HumanInputScope & {
15
+ liveSessionId: string;
16
+ identity: SecureBrowserIdentity;
17
+ profilePreferences?: BrowserProfilePreferences;
18
+ profileOwner?: BrowserProfileOwner;
19
+ initialControl?: {
20
+ controlEpoch: number;
21
+ mode: BrowserLiveMode;
22
+ private: boolean;
23
+ };
24
+ recordingDirectory: string;
25
+ isAuthorized: () => boolean;
26
+ onFrame: (frame: Buffer) => void;
27
+ onRecording: (recording: BrowserLiveRecording) => void;
28
+ onFailure?: (code: string, controlEpoch: number) => void;
29
+ onState?: (update: {
30
+ controlEpoch: number;
31
+ mode: BrowserLiveMode;
32
+ state: Record<string, unknown>;
33
+ }) => boolean;
34
+ };
35
+ export type BrowserLivePort = {
36
+ control: {
37
+ epoch: number;
38
+ mode: BrowserLiveMode;
39
+ private: boolean;
40
+ connected: boolean;
41
+ };
42
+ observations: BrowserObservations;
43
+ active: () => {
44
+ page: Page;
45
+ tabId: string;
46
+ };
47
+ pages: () => Page[];
48
+ queue: <T>(work: () => Promise<T>) => Promise<T>;
49
+ state: () => Promise<Record<string, unknown>>;
50
+ authorized: () => boolean;
51
+ fullNetwork: () => boolean;
52
+ selectTab: (tabId: string) => Promise<void>;
53
+ release: () => Promise<void>;
54
+ profile: (profile: NonNullable<BrowserLiveControl['profile']>, options: BrowserLiveOptions) => Promise<void>;
55
+ };
56
+ export type BrowserLiveAck = {
57
+ type: 'control.result';
58
+ requestId: string;
59
+ liveSessionId: string;
60
+ controlEpoch: number;
61
+ mode: BrowserLiveMode;
62
+ ok: boolean;
63
+ error?: string;
64
+ state?: Record<string, unknown>;
65
+ };
66
+ /** Reads SOF JPEG dimensions without decoding or allocating an image. */
67
+ export declare function jpegDimensions(jpeg: Buffer): {
68
+ width: number;
69
+ height: number;
70
+ };
71
+ export declare function browserAuthPage(value: string): boolean;
72
+ export declare class BrowserLiveHandle {
73
+ private readonly options;
74
+ private readonly port;
75
+ private page?;
76
+ private segment?;
77
+ private recordingMode;
78
+ private sequence;
79
+ private lastFrameAt;
80
+ private generation;
81
+ private closed;
82
+ private stopped;
83
+ private stateFingerprint;
84
+ private lastStatePoll;
85
+ private readonly requests;
86
+ private poll?;
87
+ private trailingFrame?;
88
+ private trailingCapturePending;
89
+ private profileChoicesPending?;
90
+ constructor(options: BrowserLiveOptions, port: BrowserLivePort);
91
+ get mode(): BrowserLiveMode;
92
+ get controlEpoch(): number;
93
+ get private(): boolean;
94
+ private assertAuthorized;
95
+ state(): Promise<Record<string, unknown>>;
96
+ start(): Promise<void>;
97
+ private captureQueue;
98
+ private capture;
99
+ private stopCapture;
100
+ private stopCaptureInner;
101
+ pauseRecording(): Promise<void>;
102
+ private syncing?;
103
+ private sync;
104
+ private publishCurrentState;
105
+ private syncInner;
106
+ private cancelTrailingFrame;
107
+ private scheduleTrailingFrame;
108
+ private emitFrame;
109
+ private refreshFrame;
110
+ control(frame: BrowserLiveControl): Promise<BrowserLiveAck>;
111
+ block(epoch?: number): void;
112
+ settled(): Promise<void>;
113
+ disconnect(): void;
114
+ }
@@ -0,0 +1,455 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { randomUUID } from 'node:crypto';
4
+ import { applyPageInteraction, pageHasSecretFocus, releasePageInput } from "./terminal-browser-page-input.js";
5
+ import { decryptBrowserHumanInput } from "./terminal-browser-human-input.js";
6
+ import { BROWSER_LIVE_MAX_FRAME_BYTES, validBrowserLiveControl, safeBrowserLiveState } from "./terminal-browser-live-protocol.js";
7
+ /** Reads SOF JPEG dimensions without decoding or allocating an image. */
8
+ export function jpegDimensions(jpeg) {
9
+ let cursor = 2;
10
+ while (cursor + 4 <= jpeg.length) {
11
+ if (jpeg[cursor++] !== 0xff)
12
+ throw new Error('invalid_browser_live_jpeg');
13
+ while (jpeg[cursor] === 0xff)
14
+ cursor++;
15
+ const marker = jpeg[cursor++];
16
+ if (marker === 0xda || marker === 0xd9)
17
+ break;
18
+ const length = jpeg.readUInt16BE(cursor);
19
+ if (length < 2 || cursor + length > jpeg.length)
20
+ break;
21
+ if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker))
22
+ return { height: jpeg.readUInt16BE(cursor + 3), width: jpeg.readUInt16BE(cursor + 5) };
23
+ cursor += length;
24
+ }
25
+ throw new Error('invalid_browser_live_jpeg');
26
+ }
27
+ export function browserAuthPage(value) {
28
+ try {
29
+ return /(?:^|[/_.-])(?:login|signin|sign-in|auth|oauth|saml|mfa|two-factor)(?:[/_.-]|$)/iu.test(new URL(value).pathname);
30
+ }
31
+ catch {
32
+ return true;
33
+ }
34
+ }
35
+ export class BrowserLiveHandle {
36
+ options;
37
+ port;
38
+ page;
39
+ segment;
40
+ recordingMode = 'off';
41
+ sequence = 0;
42
+ lastFrameAt = 0;
43
+ generation = 0;
44
+ closed = false;
45
+ stopped = false;
46
+ stateFingerprint = '';
47
+ lastStatePoll = 0;
48
+ requests = new Set();
49
+ poll;
50
+ trailingFrame;
51
+ trailingCapturePending = false;
52
+ profileChoicesPending;
53
+ constructor(options, port) { this.options = options; this.port = port; }
54
+ get mode() { return this.port.control.mode; }
55
+ get controlEpoch() { return this.port.control.epoch; }
56
+ get private() { return this.port.control.private; }
57
+ assertAuthorized() {
58
+ if (this.closed || !this.options.isAuthorized() || !this.port.authorized())
59
+ throw new Error('browser_live_scope_expired');
60
+ }
61
+ async state() {
62
+ this.assertAuthorized();
63
+ const state = await this.port.state();
64
+ const preferences = this.options.profilePreferences;
65
+ const owner = this.options.profileOwner;
66
+ let profiles = [];
67
+ if (preferences && owner) {
68
+ const pending = this.profileChoicesPending || preferences.choicesAsync(owner, { selectedName: state.browserProfile?.persistent ? state.browserProfile.name : undefined });
69
+ this.profileChoicesPending = pending;
70
+ try {
71
+ profiles = await pending;
72
+ }
73
+ finally {
74
+ if (this.profileChoicesPending === pending)
75
+ this.profileChoicesPending = undefined;
76
+ }
77
+ }
78
+ const selected = state.browserProfile;
79
+ const profile = preferences && owner ? selected?.persistent
80
+ ? profiles.find(choice => choice.persistent && choice.name === selected.name) || { ...selected, default: false }
81
+ : profiles[0] : selected;
82
+ this.assertAuthorized();
83
+ return { ...state, profile, profiles, private: this.private, frameSequence: this.sequence, recording: { mode: this.recordingMode } };
84
+ }
85
+ async start() {
86
+ this.assertAuthorized();
87
+ this.stopped = false;
88
+ this.port.control.connected = true;
89
+ await this.sync();
90
+ // Website-created popups and model tab switches need no model call to refresh the active stream.
91
+ if (this.poll)
92
+ clearInterval(this.poll);
93
+ this.poll = setInterval(() => {
94
+ void this.sync().catch(error => {
95
+ const known = ['browser_profile_busy', 'browser_profile_changed', 'browser_profile_corrupt',
96
+ 'browser_profile_keystore_unavailable', 'browser_observation_unavailable', 'browser_observation_stale',
97
+ 'browser_live_scope_expired', 'browser_recording_network_required', 'browser_recording_path_invalid'];
98
+ const code = error instanceof Error && known.includes(error.message) ? error.message : 'browser_live_capture_failed';
99
+ try {
100
+ this.options.onFailure?.(code, this.controlEpoch);
101
+ }
102
+ catch { /* Diagnostics cannot bypass the local fence. */ }
103
+ this.block();
104
+ });
105
+ }, 200);
106
+ this.poll.unref();
107
+ }
108
+ captureQueue = Promise.resolve();
109
+ capture(work) {
110
+ const task = this.captureQueue.catch(() => undefined).then(work);
111
+ this.captureQueue = task;
112
+ return task;
113
+ }
114
+ stopCapture() { return this.capture(() => this.stopCaptureInner()); }
115
+ async stopCaptureInner() {
116
+ this.cancelTrailingFrame();
117
+ const page = this.page;
118
+ const segment = this.segment;
119
+ this.page = undefined;
120
+ this.segment = undefined;
121
+ this.generation++;
122
+ if (page && !page.isClosed())
123
+ await page.screencast.stop().catch(() => undefined);
124
+ if (segment) {
125
+ const file = fs.lstatSync(segment.path, { throwIfNoEntry: false });
126
+ if (file?.isFile() && !file.isSymbolicLink() && file.size > 0 && file.size <= 256 * 1024 * 1024) {
127
+ fs.chmodSync(segment.path, 0o600);
128
+ this.options.onRecording({ ...segment, size: file.size });
129
+ }
130
+ else if (file && file.size === 0)
131
+ fs.unlinkSync(segment.path);
132
+ }
133
+ }
134
+ async pauseRecording() {
135
+ if (!this.segment && this.recordingMode === 'off')
136
+ return;
137
+ this.generation++;
138
+ this.port.control.private = true;
139
+ await this.stopCapture();
140
+ if (!this.closed)
141
+ await this.sync();
142
+ }
143
+ syncing;
144
+ async sync() {
145
+ if (this.syncing)
146
+ return this.syncing;
147
+ this.syncing = this.capture(() => this.syncInner()).finally(() => { this.syncing = undefined; });
148
+ return this.syncing;
149
+ }
150
+ async publishCurrentState(force = false) {
151
+ if (!this.options.onState || !['observe', 'human'].includes(this.mode) || !force && Date.now() - this.lastStatePoll < 1000)
152
+ return false;
153
+ this.lastStatePoll = Date.now();
154
+ const epoch = this.controlEpoch;
155
+ const mode = this.mode;
156
+ const state = safeBrowserLiveState(await this.state());
157
+ this.assertAuthorized();
158
+ if (this.mode !== mode || epoch !== this.controlEpoch)
159
+ return false;
160
+ const fingerprint = JSON.stringify({ mode, epoch, tabs: state.tabs, profile: state.profile, private: state.private });
161
+ if (fingerprint !== this.stateFingerprint && this.options.onState({ controlEpoch: epoch, mode, state })) {
162
+ this.stateFingerprint = fingerprint;
163
+ return true;
164
+ }
165
+ return false;
166
+ }
167
+ async syncInner() {
168
+ if (this.closed || this.stopped)
169
+ return;
170
+ this.assertAuthorized();
171
+ const { page, tabId } = this.port.active();
172
+ if (page === this.page) {
173
+ const changed = await this.publishCurrentState();
174
+ if (changed)
175
+ await this.refreshFrame();
176
+ // Chromium emits only damaged frames. Keep the displayed human observation fresh even
177
+ // while the user reads a static page, using actual bounded viewport captures.
178
+ if (this.mode === 'human' && Date.now() - this.lastFrameAt >= 2000)
179
+ await this.refreshFrame(this.controlEpoch);
180
+ return;
181
+ }
182
+ await this.stopCaptureInner();
183
+ if (this.closed || page.isClosed())
184
+ return;
185
+ this.assertAuthorized();
186
+ if (browserAuthPage(page.url()) || await pageHasSecretFocus(page))
187
+ this.port.control.private = true;
188
+ await this.publishCurrentState(true);
189
+ const generation = ++this.generation;
190
+ this.page = page;
191
+ let recordingPath;
192
+ if (this.recordingMode !== 'off' && !this.private && this.mode !== 'blocked') {
193
+ if (this.recordingMode !== 'local' && !this.port.fullNetwork())
194
+ throw new Error('browser_recording_network_required');
195
+ const directory = this.options.recordingDirectory;
196
+ fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
197
+ const info = fs.lstatSync(directory);
198
+ if (!info.isDirectory() || info.isSymbolicLink() || fs.realpathSync(directory) !== directory)
199
+ throw new Error('browser_recording_path_invalid');
200
+ fs.chmodSync(directory, 0o700);
201
+ const recordingId = randomUUID();
202
+ const name = `browser-${recordingId}.webm`;
203
+ recordingPath = path.join(directory, name);
204
+ fs.closeSync(fs.openSync(recordingPath, 'wx', 0o600));
205
+ this.segment = { recordingId, name, path: recordingPath, size: 0, mode: this.recordingMode };
206
+ }
207
+ await page.screencast.start({ quality: 70, size: { width: Math.min(page.viewportSize().width, 1280),
208
+ height: Math.min(page.viewportSize().height, 900) }, ...(recordingPath ? { path: recordingPath } : {}),
209
+ onFrame: frame => {
210
+ if (this.closed || generation !== this.generation || !this.options.isAuthorized() || !this.port.authorized()
211
+ || this.port.active().page !== page)
212
+ return;
213
+ if (Date.now() - this.lastFrameAt < 200) {
214
+ this.scheduleTrailingFrame(page, tabId, generation);
215
+ return;
216
+ }
217
+ this.cancelTrailingFrame();
218
+ this.lastFrameAt = Date.now();
219
+ try {
220
+ this.emitFrame(frame.data, page, tabId);
221
+ if (this.segment && fs.statSync(this.segment.path).size > 250 * 1024 * 1024)
222
+ void this.pauseRecording();
223
+ }
224
+ catch { /* A destroyed page/frame is discarded, never replayed. */ }
225
+ } });
226
+ await this.refreshFrame();
227
+ }
228
+ cancelTrailingFrame() {
229
+ if (this.trailingFrame)
230
+ clearTimeout(this.trailingFrame);
231
+ this.trailingFrame = undefined;
232
+ }
233
+ scheduleTrailingFrame(page, tabId, generation) {
234
+ if (this.trailingFrame || this.trailingCapturePending)
235
+ return;
236
+ const epoch = this.controlEpoch, mode = this.mode, privateFrame = this.private;
237
+ const current = () => !this.closed && !this.stopped && generation === this.generation
238
+ && epoch === this.controlEpoch && mode === this.mode && privateFrame === this.private
239
+ && mode !== 'blocked' && this.options.isAuthorized() && this.port.authorized()
240
+ && !page.isClosed() && this.port.active().page === page && this.port.active().tabId === tabId;
241
+ this.trailingFrame = setTimeout(() => {
242
+ this.trailingFrame = undefined;
243
+ this.trailingCapturePending = true;
244
+ // Damage events stop when a page becomes static. Capture the actual final
245
+ // viewport under the mutation queue instead of restamping buffered old pixels.
246
+ void this.port.queue(() => this.capture(async () => {
247
+ if (!current())
248
+ return;
249
+ const jpeg = await page.screenshot({ type: 'jpeg', quality: 65, scale: 'css', timeout: 2000 });
250
+ if (!current())
251
+ return;
252
+ this.lastFrameAt = Date.now();
253
+ this.emitFrame(jpeg, page, tabId);
254
+ })).catch(() => undefined).finally(() => { this.trailingCapturePending = false; });
255
+ }, Math.max(0, 200 - (Date.now() - this.lastFrameAt)));
256
+ this.trailingFrame.unref();
257
+ }
258
+ emitFrame(data, page, tabId) {
259
+ const observation = this.port.observations.fresh(page, tabId);
260
+ const image = jpegDimensions(data);
261
+ const metadata = { protocol: 1, liveSessionId: this.options.liveSessionId,
262
+ browserSessionId: this.options.browserSessionId, tabId, epoch: this.controlEpoch, sequence: ++this.sequence,
263
+ timestamp: Date.now(), observationId: observation.id, width: observation.width, height: observation.height,
264
+ imageWidth: image.width, imageHeight: image.height, format: 'jpeg', private: this.private };
265
+ const header = Buffer.from(JSON.stringify(metadata));
266
+ if (4 + header.length + data.length > BROWSER_LIVE_MAX_FRAME_BYTES)
267
+ return;
268
+ const packet = Buffer.allocUnsafe(4 + header.length + data.length);
269
+ packet.writeUInt32BE(header.length);
270
+ header.copy(packet, 4);
271
+ data.copy(packet, 4 + header.length);
272
+ this.options.onFrame(packet);
273
+ }
274
+ async refreshFrame(humanEpoch) {
275
+ // A static page can emit its last native frame before input invalidates geometry. Produce a fresh
276
+ // bounded viewport frame after the action; the transport coalesces it into the same five-FPS stream.
277
+ for (let attempt = 0; attempt < 2; attempt++) {
278
+ this.assertAuthorized();
279
+ const { page, tabId } = this.port.active();
280
+ const epoch = this.controlEpoch, mode = this.mode, generation = this.generation, privateFrame = this.private;
281
+ let jpeg;
282
+ try {
283
+ jpeg = await page.screenshot({ type: 'jpeg', quality: 65, scale: 'css', timeout: humanEpoch === undefined ? 5000 : 2000 });
284
+ }
285
+ catch (error) {
286
+ this.assertAuthorized();
287
+ // A closed, replaced page is an obsolete capture, not a failure of the
288
+ // still-authorized successor. All errors on the current page remain fatal.
289
+ if (!this.closed && !this.stopped && page.isClosed() && this.port.active().page !== page
290
+ && epoch === this.controlEpoch && mode === this.mode && privateFrame === this.private)
291
+ return;
292
+ throw error;
293
+ }
294
+ this.assertAuthorized();
295
+ // Awaiting Chromium can span a takeover, page replacement or local fail-closed
296
+ // transition. Pixels captured under the previous scope must never acquire its
297
+ // successor's observation identity or control epoch.
298
+ if (this.closed || this.stopped || epoch !== this.controlEpoch || mode !== this.mode
299
+ || generation !== this.generation || privateFrame !== this.private)
300
+ return;
301
+ if (humanEpoch !== undefined && (this.stopped || this.mode !== 'human' || this.controlEpoch !== humanEpoch))
302
+ return;
303
+ if (this.port.active().page !== page || this.port.active().tabId !== tabId)
304
+ continue;
305
+ this.lastFrameAt = Date.now();
306
+ this.emitFrame(jpeg, page, tabId);
307
+ return;
308
+ }
309
+ throw new Error('browser_observation_stale');
310
+ }
311
+ async control(frame) {
312
+ const ack = (ok, error, state) => ({
313
+ type: 'control.result', requestId: frame.requestId, liveSessionId: this.options.liveSessionId,
314
+ controlEpoch: this.controlEpoch, mode: this.mode, ok, ...(error ? { error } : {}), ...(state ? { state } : {})
315
+ });
316
+ try {
317
+ this.assertAuthorized();
318
+ if (!validBrowserLiveControl(frame) || frame.liveSessionId !== this.options.liveSessionId || this.requests.has(frame.requestId))
319
+ throw new Error('browser_live_control_invalid');
320
+ if (this.requests.size >= 4096)
321
+ throw new Error('browser_live_reconnect_required');
322
+ this.requests.add(frame.requestId);
323
+ const transition = ['takeover', 'release', 'profile', 'select_tab'].includes(frame.action)
324
+ || frame.action === 'stop' && this.mode !== 'observe';
325
+ if (transition ? frame.controlEpoch !== this.controlEpoch + 1
326
+ : frame.action === 'start' ? frame.controlEpoch > this.controlEpoch : frame.controlEpoch !== this.controlEpoch)
327
+ throw new Error('browser_live_epoch_stale');
328
+ const priorMode = this.mode;
329
+ if (['input', 'profile', 'select_tab'].includes(frame.action) && priorMode !== 'human'
330
+ || frame.action === 'recording' && priorMode === 'blocked' && frame.recording?.mode !== 'off')
331
+ throw new Error('browser_live_human_owner_required');
332
+ // Fence every queued model operation immediately, before awaiting the shared session queue.
333
+ if (transition) {
334
+ this.port.control.epoch = frame.controlEpoch;
335
+ this.port.control.mode = 'blocked';
336
+ this.port.observations.invalidate();
337
+ }
338
+ return await this.port.queue(async () => {
339
+ this.assertAuthorized();
340
+ if (frame.action !== 'start' && frame.controlEpoch !== this.controlEpoch)
341
+ throw new Error('browser_live_epoch_stale');
342
+ if (frame.action === 'takeover') {
343
+ this.port.control.private = frame.private !== false;
344
+ if (this.private)
345
+ await this.stopCapture();
346
+ for (const page of this.port.pages())
347
+ await releasePageInput(page);
348
+ this.port.control.mode = 'human';
349
+ }
350
+ else if (frame.action === 'release') {
351
+ await this.stopCapture();
352
+ await this.port.release();
353
+ this.port.control.private = false;
354
+ }
355
+ else if (frame.action === 'input') {
356
+ const interaction = decryptBrowserHumanInput(frame, this.options, this.options.identity);
357
+ const { page, tabId } = this.port.active();
358
+ const observation = this.port.observations.require(interaction.observationId, page, tabId, true);
359
+ if (this.private || await pageHasSecretFocus(page)) {
360
+ this.port.control.private = true;
361
+ await this.stopCapture();
362
+ }
363
+ await applyPageInteraction(page, interaction, observation, true);
364
+ this.port.observations.invalidate();
365
+ }
366
+ else if (frame.action === 'profile') {
367
+ this.port.control.private = true;
368
+ await this.stopCapture();
369
+ await this.port.profile(frame.profile, this.options);
370
+ this.port.control.mode = 'human';
371
+ }
372
+ else if (frame.action === 'select_tab') {
373
+ await this.stopCapture();
374
+ await this.port.selectTab(frame.tabId);
375
+ this.port.control.mode = 'human';
376
+ }
377
+ else if (frame.action === 'recording') {
378
+ const mode = frame.recording.mode;
379
+ if (mode !== 'off' && this.private) {
380
+ if (this.mode !== 'observe' || browserAuthPage(this.port.active().page.url())
381
+ || await pageHasSecretFocus(this.port.active().page))
382
+ throw new Error('browser_recording_private');
383
+ this.port.control.private = false;
384
+ }
385
+ if (mode !== 'off' && mode !== 'local' && !this.port.fullNetwork())
386
+ throw new Error('browser_recording_network_required');
387
+ await this.stopCapture();
388
+ this.recordingMode = mode;
389
+ }
390
+ else if (frame.action === 'stop') {
391
+ this.stopped = true;
392
+ this.port.control.connected = false;
393
+ if (this.poll)
394
+ clearInterval(this.poll);
395
+ this.poll = undefined;
396
+ await this.stopCapture();
397
+ if (priorMode !== 'observe')
398
+ this.port.control.mode = 'blocked';
399
+ return ack(true);
400
+ }
401
+ else if (frame.action === 'start') {
402
+ await this.start();
403
+ }
404
+ this.lastFrameAt = 0;
405
+ if (frame.action === 'refresh')
406
+ await this.stopCapture();
407
+ await this.sync();
408
+ await this.refreshFrame();
409
+ const state = await this.state();
410
+ this.assertAuthorized();
411
+ if (frame.action === 'release') {
412
+ this.port.control.mode = 'observe';
413
+ await this.stopCapture();
414
+ await this.sync();
415
+ }
416
+ return ack(true, undefined, state);
417
+ });
418
+ }
419
+ catch (error) {
420
+ const message = error instanceof Error && /^browser_[a-z_]+$/u.test(error.message) ? error.message : 'browser_live_control_failed';
421
+ return ack(false, message);
422
+ }
423
+ }
424
+ block(epoch) {
425
+ if (this.closed)
426
+ return;
427
+ if (epoch !== undefined && epoch <= this.controlEpoch && this.mode === 'blocked')
428
+ return;
429
+ this.cancelTrailingFrame();
430
+ this.generation++;
431
+ this.port.control.epoch = epoch === undefined ? this.controlEpoch + 1 : Math.max(this.controlEpoch, epoch);
432
+ this.port.control.mode = 'blocked';
433
+ this.port.control.private = true;
434
+ this.port.observations.invalidate();
435
+ void this.stopCapture();
436
+ for (const page of this.port.pages())
437
+ void releasePageInput(page);
438
+ }
439
+ async settled() { await this.captureQueue.catch(() => undefined); }
440
+ disconnect() {
441
+ if (this.closed)
442
+ return;
443
+ if (this.mode === 'human')
444
+ this.block();
445
+ this.cancelTrailingFrame();
446
+ this.generation++;
447
+ this.closed = true;
448
+ this.port.control.connected = false;
449
+ if (this.poll)
450
+ clearInterval(this.poll);
451
+ void this.stopCapture();
452
+ for (const page of this.port.pages())
453
+ void releasePageInput(page);
454
+ }
455
+ }
@@ -0,0 +1,10 @@
1
+ import type { Page } from 'playwright-core';
2
+ import type { BrowserObservation } from './terminal-browser-interaction.ts';
3
+ /** Media frames share a generation: streaming must not invalidate a model's recent screenshot. */
4
+ export declare class BrowserObservations {
5
+ private generation;
6
+ private readonly entries;
7
+ invalidate(): void;
8
+ fresh(page: Page, tabId: string): BrowserObservation;
9
+ require(id: string, page: Page, tabId: string, human?: boolean): BrowserObservation;
10
+ }
@@ -0,0 +1,27 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ /** Media frames share a generation: streaming must not invalidate a model's recent screenshot. */
3
+ export class BrowserObservations {
4
+ generation = 0;
5
+ entries = new Map();
6
+ invalidate() { this.generation++; this.entries.clear(); }
7
+ fresh(page, tabId) {
8
+ const viewport = page.viewportSize();
9
+ if (!viewport || page.isClosed())
10
+ throw new Error('browser_observation_unavailable');
11
+ const observation = { id: randomUUID(), tabId, width: viewport.width, height: viewport.height };
12
+ this.entries.set(observation.id, { ...observation, page, url: page.url(), generation: this.generation, createdAt: Date.now() });
13
+ while (this.entries.size > 1024)
14
+ this.entries.delete(this.entries.keys().next().value);
15
+ return observation;
16
+ }
17
+ require(id, page, tabId, human = false) {
18
+ const observed = this.entries.get(id);
19
+ const viewport = page.viewportSize();
20
+ if (!observed || observed.generation !== this.generation || observed.page !== page
21
+ || observed.tabId !== tabId || observed.url !== page.url() || !viewport
22
+ || observed.width !== viewport.width || observed.height !== viewport.height
23
+ || Date.now() - observed.createdAt > (human ? 5_000 : 120_000))
24
+ throw new Error('browser_observation_stale');
25
+ return { id: observed.id, tabId: observed.tabId, width: observed.width, height: observed.height };
26
+ }
27
+ }
@@ -0,0 +1,8 @@
1
+ import type { Page } from 'playwright-core';
2
+ import { type BrowserInteraction, type BrowserObservation } from './terminal-browser-interaction.ts';
3
+ /** CAPTCHA answers are model-solvable; explicit password/MFA controls remain private. */
4
+ export declare function secretControlAttributes(attributes: Array<string | null>): boolean;
5
+ export declare function pageHasSecretFocus(page: Page): Promise<boolean>;
6
+ export declare function clearSecretInputs(page: Page): Promise<void>;
7
+ export declare function releasePageInput(page: Page): Promise<void>;
8
+ export declare function applyPageInteraction(page: Page, interaction: BrowserInteraction, observation: BrowserObservation, human?: boolean, onAttempt?: () => void): Promise<void>;