@revoengine/cli 1.0.39 → 2.1.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 (41) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +15 -9
  3. package/dist/src/argument-contract.js +1 -1
  4. package/dist/src/automation-contract.generated.d.ts +91 -34
  5. package/dist/src/automation-contract.generated.js +109 -34
  6. package/dist/src/client.d.ts +3 -0
  7. package/dist/src/commands/component.js +16 -0
  8. package/dist/src/commands/terminal-browser-human-input.d.ts +28 -0
  9. package/dist/src/commands/terminal-browser-human-input.js +56 -7
  10. package/dist/src/commands/terminal-browser-live-protocol.d.ts +9 -1
  11. package/dist/src/commands/terminal-browser-live-protocol.js +16 -3
  12. package/dist/src/commands/terminal-browser-live-transport.d.ts +2 -0
  13. package/dist/src/commands/terminal-browser-live-transport.js +21 -5
  14. package/dist/src/commands/terminal-browser-live.d.ts +18 -1
  15. package/dist/src/commands/terminal-browser-live.js +190 -14
  16. package/dist/src/commands/terminal-browser-observation.d.ts +1 -1
  17. package/dist/src/commands/terminal-browser-observation.js +10 -1
  18. package/dist/src/commands/terminal-browser-page-input.d.ts +1 -0
  19. package/dist/src/commands/terminal-browser-page-input.js +20 -0
  20. package/dist/src/commands/terminal-browser-profile-sync.d.ts +5 -1
  21. package/dist/src/commands/terminal-browser-profile-sync.js +13 -2
  22. package/dist/src/commands/terminal-browser-profile-sync.protocol.d.ts +2 -0
  23. package/dist/src/commands/terminal-browser.d.ts +17 -0
  24. package/dist/src/commands/terminal-browser.js +310 -104
  25. package/dist/src/commands/terminal.js +104 -24
  26. package/dist/src/endpoint-emulator.js +9 -10
  27. package/dist/src/project.js +1 -0
  28. package/dist/src/request-contract.d.ts +2 -0
  29. package/dist/src/request-contract.js +11 -1
  30. package/dist/src/resource-syncs/automation-input.d.ts +2 -2
  31. package/dist/src/resource-syncs/automation-input.js +7 -17
  32. package/dist/src/resource-syncs/event-sync.d.ts +2 -0
  33. package/dist/src/resource-syncs/event-sync.js +18 -8
  34. package/dist/src/resource-syncs/job-template-sync.d.ts +2 -0
  35. package/dist/src/resource-syncs/job-template-sync.js +6 -1
  36. package/dist/src/resource-syncs/runtime-definition-validation.js +10 -2
  37. package/dist/src/resource-syncs/schedule-sync.js +0 -1
  38. package/dist/src/sync-omit.js +3 -1
  39. package/dist/src/types.d.ts +12 -5
  40. package/dist/src/ui.js +1 -1
  41. package/package.json +1 -1
@@ -11,3 +11,31 @@ export type HumanInputScope = {
11
11
  export declare function decryptBrowserHumanInput(frame: BrowserLiveControl, scope: HumanInputScope, identity: SecureBrowserIdentity): BrowserInteraction & {
12
12
  focusId?: string;
13
13
  };
14
+ type Point = {
15
+ x: number;
16
+ y: number;
17
+ };
18
+ export type BrowserPointer = {
19
+ observationId: string;
20
+ gestureId: string;
21
+ sequence: number;
22
+ } & ({
23
+ phase: 'down';
24
+ button: 'left' | 'right' | 'middle';
25
+ modifiers?: BrowserInteraction['modifiers'];
26
+ } & Point | {
27
+ phase: 'move' | 'up';
28
+ } & Point | {
29
+ phase: 'cancel';
30
+ });
31
+ export declare function decryptBrowserPointer(frame: BrowserLiveControl, scope: HumanInputScope, identity: SecureBrowserIdentity): BrowserPointer;
32
+ export declare function decryptClipboardRequest(frame: BrowserLiveControl, scope: HumanInputScope, identity: SecureBrowserIdentity): {
33
+ observationId: string;
34
+ key: Buffer<ArrayBufferLike>;
35
+ };
36
+ export declare function encryptBrowserSelection(frame: BrowserLiveControl, key: Buffer, text: string): {
37
+ iv: string;
38
+ ciphertext: string;
39
+ tag: string;
40
+ } | undefined;
41
+ export {};
@@ -1,5 +1,5 @@
1
- import { createDecipheriv, createPublicKey, diffieHellman, hkdfSync } from 'node:crypto';
2
- import { browserLiveInputAad, BROWSER_LIVE_INPUT_INFO } from "./terminal-browser-live-protocol.js";
1
+ import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, hkdfSync, randomBytes } from 'node:crypto';
2
+ import { browserClipboardAad, browserLiveInputAad, BROWSER_LIVE_INPUT_INFO } from "./terminal-browser-live-protocol.js";
3
3
  import { validBrowserInteraction } from "./terminal-browser-interaction.js";
4
4
  function bytes(value, size) {
5
5
  const data = Buffer.from(value, 'base64');
@@ -7,7 +7,7 @@ function bytes(value, size) {
7
7
  throw new Error('browser_private_input_invalid');
8
8
  return data;
9
9
  }
10
- export function decryptBrowserHumanInput(frame, scope, identity) {
10
+ function decryptPayload(frame, scope, identity, validate) {
11
11
  const input = frame.privateInput;
12
12
  if (!input || input.keyId !== identity.keyId || !Number.isSafeInteger(input.expiresAt)
13
13
  || input.expiresAt <= Date.now() || input.expiresAt > Date.now() + 60_000)
@@ -29,11 +29,9 @@ export function decryptBrowserHumanInput(frame, scope, identity) {
29
29
  throw new Error();
30
30
  plaintext = Buffer.concat([cipher.update(ciphertext), cipher.final()]);
31
31
  const interaction = JSON.parse(plaintext.toString('utf8'));
32
- const { focusId, ...ordinary } = interaction;
33
- if (!validBrowserInteraction(ordinary) || ordinary.observationId !== input.observationId
34
- || focusId !== undefined && (ordinary.kind !== 'text' || typeof focusId !== 'string' || !/^[a-f0-9-]{36}$/iu.test(focusId)))
32
+ if (interaction?.observationId !== input.observationId)
35
33
  throw new Error();
36
- return interaction;
34
+ return validate(interaction);
37
35
  }
38
36
  catch {
39
37
  throw new Error('browser_private_input_invalid');
@@ -44,3 +42,54 @@ export function decryptBrowserHumanInput(frame, scope, identity) {
44
42
  plaintext?.fill(0);
45
43
  }
46
44
  }
45
+ export function decryptBrowserHumanInput(frame, scope, identity) {
46
+ return decryptPayload(frame, scope, identity, interaction => {
47
+ const { focusId, ...ordinary } = interaction;
48
+ if (!validBrowserInteraction(ordinary)
49
+ || focusId !== undefined && (ordinary.kind !== 'text' || typeof focusId !== 'string' || !/^[a-f0-9-]{36}$/iu.test(focusId)))
50
+ throw new Error();
51
+ return interaction;
52
+ });
53
+ }
54
+ export function decryptBrowserPointer(frame, scope, identity) {
55
+ return decryptPayload(frame, scope, identity, pointer => {
56
+ const { phase, gestureId, sequence, ...point } = pointer;
57
+ if (typeof gestureId !== 'string' || !/^[a-f0-9-]{36}$/iu.test(gestureId)
58
+ || !Number.isSafeInteger(sequence) || sequence < 0)
59
+ throw new Error();
60
+ if (phase === 'cancel') {
61
+ if (Object.keys(point).length !== 1)
62
+ throw new Error();
63
+ }
64
+ else {
65
+ if (!['down', 'move', 'up'].includes(phase)
66
+ || !validBrowserInteraction({ ...point, kind: phase === 'down' ? 'click' : 'move' })
67
+ || phase === 'down' && (sequence !== 0 || !point.button))
68
+ throw new Error();
69
+ }
70
+ return pointer;
71
+ });
72
+ }
73
+ export function decryptClipboardRequest(frame, scope, identity) {
74
+ return decryptPayload(frame, scope, identity, payload => {
75
+ if (payload.kind !== 'copy_selection' || typeof payload.replyKey !== 'string'
76
+ || Object.keys(payload).some(key => !['kind', 'observationId', 'replyKey'].includes(key)))
77
+ throw new Error();
78
+ return { observationId: payload.observationId, key: bytes(payload.replyKey, 32) };
79
+ });
80
+ }
81
+ export function encryptBrowserSelection(frame, key, text) {
82
+ const plaintext = Buffer.from(text, 'utf8');
83
+ try {
84
+ if (!plaintext.length || plaintext.length > 4096)
85
+ return undefined;
86
+ const iv = randomBytes(12);
87
+ const cipher = createCipheriv('aes-256-gcm', key, iv);
88
+ cipher.setAAD(browserClipboardAad(frame));
89
+ return { iv: iv.toString('base64'), ciphertext: Buffer.concat([cipher.update(plaintext), cipher.final()]).toString('base64'),
90
+ tag: cipher.getAuthTag().toString('base64') };
91
+ }
92
+ finally {
93
+ plaintext.fill(0);
94
+ }
95
+ }
@@ -39,7 +39,7 @@ export type BrowserLiveControl = {
39
39
  requestId: string;
40
40
  liveSessionId: string;
41
41
  controlEpoch: number;
42
- action: 'start' | 'stop' | 'takeover' | 'release' | 'input' | 'refresh' | 'profile' | 'recording' | 'recording_save' | 'select_tab' | 'settings' | 'navigate';
42
+ action: 'start' | 'stop' | 'takeover' | 'release' | 'input' | 'pointer' | 'copy_selection' | 'refresh' | 'profile' | 'recording' | 'recording_save' | 'select_tab' | 'new_tab' | 'close_tab' | 'close_session' | 'settings' | 'navigate';
43
43
  settings?: {
44
44
  fps: number;
45
45
  width: number;
@@ -115,8 +115,16 @@ export type BrowserLiveReady = BrowserLiveTarget & {
115
115
  };
116
116
  export declare const validLiveId: (value: unknown) => value is string;
117
117
  export declare const validBrowserSessionId: (value: unknown) => value is string;
118
+ /** Session-wide operations stay fenced during private tab control. */
119
+ export declare function canUseOtherBrowserTab(controlledTabId: unknown, tabId: unknown, action: string): boolean;
118
120
  export declare function validBrowserLiveOpen(value: any): value is BrowserLiveOpen;
119
121
  export declare function validBrowserLiveControl(value: any): value is BrowserLiveControl;
122
+ export declare function validBrowserClipboard(value: any): value is {
123
+ iv: string;
124
+ ciphertext: string;
125
+ tag: string;
126
+ };
127
+ export declare function browserClipboardAad(input: Pick<BrowserLiveControl, 'liveSessionId' | 'controlEpoch' | 'requestId'>): Buffer;
120
128
  export declare function browserLiveInputAad(input: {
121
129
  liveSessionId: string;
122
130
  browserSessionId: string;
@@ -13,6 +13,11 @@ const integer = (value, min, max) => Number.isSafeInteger(value) && Number(value
13
13
  const base64 = (value, min, max) => typeof value === 'string'
14
14
  && value.length <= Math.ceil(max / 3) * 4 && /^[a-z0-9+/]+={0,2}$/iu.test(value)
15
15
  && Buffer.from(value, 'base64').length >= min && Buffer.from(value, 'base64').length <= max;
16
+ /** Session-wide operations stay fenced during private tab control. */
17
+ export function canUseOtherBrowserTab(controlledTabId, tabId, action) {
18
+ return validLiveId(controlledTabId) && validLiveId(tabId) && controlledTabId !== tabId
19
+ && ['navigate', 'dom', 'screenshot', 'click', 'fill', 'check', 'select', 'press', 'scroll', 'wait_for', 'interact'].includes(action);
20
+ }
16
21
  export function validBrowserLiveOpen(value) {
17
22
  return value?.type === 'open' && value.protocol === 1 && validLiveId(value.threadId)
18
23
  && validLiveId(value.agentTerminalId) && validLiveId(value.agentTerminalWorkspaceId)
@@ -22,14 +27,15 @@ export function validBrowserLiveOpen(value) {
22
27
  export function validBrowserLiveControl(value) {
23
28
  if (value?.type !== 'browser_live_control' || value.protocol !== 1 || !validLiveId(value.requestId)
24
29
  || !validLiveId(value.liveSessionId) || !integer(value.controlEpoch, 0, Number.MAX_SAFE_INTEGER)
25
- || !['start', 'stop', 'takeover', 'release', 'input', 'refresh', 'profile', 'recording', 'recording_save', 'select_tab', 'settings', 'navigate'].includes(value.action)
30
+ || !['start', 'stop', 'takeover', 'release', 'input', 'pointer', 'copy_selection', 'refresh', 'profile', 'recording', 'recording_save', 'select_tab', 'new_tab', 'close_tab', 'close_session', 'settings', 'navigate'].includes(value.action)
26
31
  || Object.keys(value).some(key => !['type', 'protocol', 'requestId', 'liveSessionId', 'controlEpoch', 'action', 'tabId', 'private', 'privateInput', 'profile', 'recording', 'settings', 'navigation'].includes(key)))
27
32
  return false;
28
- if (value.action === 'select_tab' ? !validLiveId(value.tabId) : value.tabId !== undefined)
33
+ if (['select_tab', 'close_tab'].includes(value.action) && !validLiveId(value.tabId)
34
+ || value.tabId !== undefined && (!['select_tab', 'close_tab', 'takeover'].includes(value.action) || !validLiveId(value.tabId)))
29
35
  return false;
30
36
  if (value.private !== undefined && (value.action !== 'takeover' || typeof value.private !== 'boolean'))
31
37
  return false;
32
- if (value.action === 'input') {
38
+ if (['input', 'pointer', 'copy_selection'].includes(value.action)) {
33
39
  const input = value.privateInput;
34
40
  if (!input || !/^[a-f0-9]{64}$/u.test(input.keyId) || !base64(input.ephemeralPublicKey, 40, 128)
35
41
  || !base64(input.iv, 12, 12) || !base64(input.tag, 16, 16) || !base64(input.ciphertext, 1, 16384)
@@ -70,6 +76,13 @@ export function validBrowserLiveControl(value) {
70
76
  return false;
71
77
  return true;
72
78
  }
79
+ export function validBrowserClipboard(value) {
80
+ return !!value && base64(value.iv, 12, 12) && base64(value.ciphertext, 1, 4096) && base64(value.tag, 16, 16)
81
+ && Object.keys(value).every(key => ['iv', 'ciphertext', 'tag'].includes(key));
82
+ }
83
+ export function browserClipboardAad(input) {
84
+ return Buffer.from(JSON.stringify(['revo-browser-clipboard-v1', input.liveSessionId, input.controlEpoch, input.requestId]), 'utf8');
85
+ }
73
86
  export function browserLiveInputAad(input) {
74
87
  return Buffer.from(JSON.stringify([input.liveSessionId, input.browserSessionId, input.actorUserId,
75
88
  input.threadId, input.agentTerminalWorkspaceId ?? null, input.connectionId, input.controlEpoch,
@@ -17,6 +17,7 @@ export type BrowserLiveAttachment = {
17
17
  controlEpoch: number;
18
18
  mode: 'observe' | 'human' | 'blocked';
19
19
  private: boolean;
20
+ controlledTabId?: string;
20
21
  networkAccess: 'local' | 'full';
21
22
  browserSettings?: BrowserLiveOptions['browserSettings'];
22
23
  };
@@ -30,6 +31,7 @@ type Options = {
30
31
  socket?: (url: string, options: WebSocket.ClientOptions) => WebSocket;
31
32
  attach?: typeof attachBrowserLive;
32
33
  transfer?: typeof transferWorkspaceFile;
34
+ onInventoryChanged?: () => void;
33
35
  };
34
36
  /** Media has its own socket and buffer. No attachment token, input or signed URL is logged. */
35
37
  export declare class TerminalBrowserLiveTransport {
@@ -21,6 +21,7 @@ export function validBrowserLiveAttachment(frame) {
21
21
  && /^[a-f0-9]{64}$/u.test(item.browserSessionId) && /^[A-Za-z0-9_-]{43}$/u.test(item.attachmentToken)
22
22
  && Number.isSafeInteger(item.revision) && item.revision >= 0 && Number.isSafeInteger(item.controlEpoch) && item.controlEpoch >= 0
23
23
  && ['observe', 'human', 'blocked'].includes(item.mode) && typeof item.private === 'boolean'
24
+ && (item.controlledTabId === undefined || typeof item.controlledTabId === 'string' && UUID.test(item.controlledTabId))
24
25
  && ['local', 'full'].includes(item.networkAccess)
25
26
  && (item.browserSettings === undefined || !!item.browserSettings && Number.isInteger(item.browserSettings.fps) && item.browserSettings.fps >= 5 && item.browserSettings.fps <= 60
26
27
  && Number.isInteger(item.browserSettings.width) && item.browserSettings.width >= 320 && item.browserSettings.width <= 3840
@@ -120,13 +121,29 @@ export class TerminalBrowserLiveTransport {
120
121
  return;
121
122
  }
122
123
  if (message.type === 'browser_live_control') {
123
- if (message.action !== 'recording_save')
124
- mediaReady = false;
125
- controlInFlight = true;
126
124
  if (message.connectionId !== frame.connectionId || message.browserSessionId !== frame.browserSessionId
127
125
  || message.actorUserId !== frame.actorUserId || message.threadId !== frame.threadId
128
126
  || message.agentTerminalWorkspaceId !== frame.agentTerminalWorkspaceId)
129
127
  throw new Error('browser_live_scope_invalid');
128
+ const control = Object.fromEntries(Object.entries(message).filter(([key]) => ['type', 'protocol', 'requestId',
129
+ 'liveSessionId', 'controlEpoch', 'action', 'private', 'privateInput', 'profile', 'recording', 'tabId', 'settings', 'navigation'].includes(key)));
130
+ if (message.action === 'pointer') {
131
+ if (!handle)
132
+ throw new Error('browser_live_scope_invalid');
133
+ await handle.pointerInput(control);
134
+ return;
135
+ }
136
+ if (message.action === 'copy_selection') {
137
+ if (!handle)
138
+ throw new Error('browser_live_scope_invalid');
139
+ const encrypted = await handle.copySelection(control);
140
+ send({ type: 'browser.clipboard', protocol: 1, liveSessionId: frame.liveSessionId,
141
+ controlEpoch: message.controlEpoch, requestId: message.requestId, ...(encrypted ? { encrypted } : {}) });
142
+ return;
143
+ }
144
+ if (message.action !== 'recording_save')
145
+ mediaReady = false;
146
+ controlInFlight = true;
130
147
  if (!handle) {
131
148
  if (message.action !== 'start' || message.controlEpoch !== frame.controlEpoch)
132
149
  throw new Error('browser_live_scope_invalid');
@@ -156,10 +173,9 @@ export class TerminalBrowserLiveTransport {
156
173
  return;
157
174
  }
158
175
  }
159
- const control = Object.fromEntries(Object.entries(message).filter(([key]) => ['type', 'protocol', 'requestId',
160
- 'liveSessionId', 'controlEpoch', 'action', 'private', 'privateInput', 'profile', 'recording', 'tabId', 'settings', 'navigation'].includes(key)));
161
176
  send(await handle.control(control));
162
177
  controlInFlight = false;
178
+ this.options.onInventoryChanged?.();
163
179
  return;
164
180
  }
165
181
  if (message.type === 'browser_recording_upload') {
@@ -33,6 +33,7 @@ export type BrowserLiveOptions = HumanInputScope & {
33
33
  controlEpoch: number;
34
34
  mode: BrowserLiveMode;
35
35
  private: boolean;
36
+ tabId?: string;
36
37
  };
37
38
  recordingDirectory: string;
38
39
  isAuthorized: () => boolean;
@@ -52,6 +53,7 @@ export type BrowserLivePort = {
52
53
  mode: BrowserLiveMode;
53
54
  private: boolean;
54
55
  connected: boolean;
56
+ tabId?: string;
55
57
  };
56
58
  observations: BrowserObservations;
57
59
  active: () => {
@@ -59,11 +61,14 @@ export type BrowserLivePort = {
59
61
  tabId: string;
60
62
  };
61
63
  pages: () => Page[];
62
- queue: <T>(work: () => Promise<T>) => Promise<T>;
64
+ queue: <T>(work: () => Promise<T>, tabInput?: boolean) => Promise<T>;
63
65
  state: () => Promise<Record<string, unknown>>;
64
66
  authorized: () => boolean;
65
67
  fullNetwork: () => boolean;
66
68
  selectTab: (tabId: string) => Promise<void>;
69
+ newTab: () => Promise<void>;
70
+ closeTab: (tabId: string) => Promise<boolean>;
71
+ closeSession: () => Promise<void>;
67
72
  release: () => Promise<void>;
68
73
  profile: (profile: NonNullable<BrowserLiveControl['profile']>, options: BrowserLiveOptions) => Promise<void>;
69
74
  };
@@ -76,6 +81,7 @@ export type BrowserLiveAck = {
76
81
  ok: boolean;
77
82
  error?: string;
78
83
  state?: Record<string, unknown>;
84
+ closed?: true;
79
85
  };
80
86
  /** Reads SOF JPEG dimensions without decoding or allocating an image. */
81
87
  export declare function jpegDimensions(jpeg: Buffer): {
@@ -84,6 +90,9 @@ export declare function jpegDimensions(jpeg: Buffer): {
84
90
  };
85
91
  export declare function browserAuthPage(value: string): boolean;
86
92
  export declare class BrowserLiveHandle {
93
+ private pointer?;
94
+ private pointerExpiry?;
95
+ private readonly pointerStarts;
87
96
  private baseOptions;
88
97
  private viewerOptions?;
89
98
  private get options();
@@ -144,9 +153,17 @@ export declare class BrowserLiveHandle {
144
153
  private scheduleTrailingFrame;
145
154
  private emitFrame;
146
155
  private refreshFrame;
156
+ private stopPointer;
157
+ pointerInput(frame: BrowserLiveControl): Promise<void>;
158
+ copySelection(frame: BrowserLiveControl): Promise<{
159
+ iv: string;
160
+ ciphertext: string;
161
+ tag: string;
162
+ } | undefined>;
147
163
  control(frame: BrowserLiveControl): Promise<BrowserLiveAck>;
148
164
  private requestRecordingSave;
149
165
  block(epoch?: number): void;
166
+ private controlledPages;
150
167
  settled(): Promise<void>;
151
168
  disconnect(): void;
152
169
  close(): void;
@@ -1,8 +1,8 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
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";
4
+ import { applyPageInteraction, pageHasSecretFocus, readPageSelection, releasePageInput } from "./terminal-browser-page-input.js";
5
+ import { decryptBrowserHumanInput, decryptBrowserPointer, decryptClipboardRequest, encryptBrowserSelection } from "./terminal-browser-human-input.js";
6
6
  import { BROWSER_LIVE_MAX_FRAME_BYTES, validBrowserLiveControl, safeBrowserLiveState } from "./terminal-browser-live-protocol.js";
7
7
  /** Reads SOF JPEG dimensions without decoding or allocating an image. */
8
8
  export function jpegDimensions(jpeg) {
@@ -33,6 +33,9 @@ export function browserAuthPage(value) {
33
33
  }
34
34
  }
35
35
  export class BrowserLiveHandle {
36
+ pointer;
37
+ pointerExpiry;
38
+ pointerStarts = new Map();
36
39
  baseOptions;
37
40
  viewerOptions;
38
41
  get options() { return this.viewerOptions ?? this.baseOptions; }
@@ -494,6 +497,137 @@ export class BrowserLiveHandle {
494
497
  }
495
498
  throw new Error('browser_observation_stale');
496
499
  }
500
+ async stopPointer(commit = false) {
501
+ if (this.pointerExpiry)
502
+ clearTimeout(this.pointerExpiry);
503
+ this.pointerExpiry = undefined;
504
+ const pointer = this.pointer;
505
+ this.pointer = undefined;
506
+ if (pointer) {
507
+ pointer.page.off('framenavigated', pointer.navigation);
508
+ if (!commit)
509
+ await pointer.page.mouse.move(-1, -1).catch(() => undefined);
510
+ await pointer.page.mouse.up({ button: pointer.button }).catch(() => undefined);
511
+ for (const key of pointer.modifiers)
512
+ await pointer.page.keyboard.up(key).catch(() => undefined);
513
+ }
514
+ }
515
+ async pointerInput(frame) {
516
+ const options = this.options;
517
+ this.assertAuthorized(options);
518
+ if (frame.action === 'pointer' && frame.liveSessionId === options.liveSessionId && frame.controlEpoch === this.controlEpoch
519
+ && Number.isSafeInteger(frame.privateInput?.expiresAt) && frame.privateInput.expiresAt <= Date.now()) {
520
+ await this.stopPointer();
521
+ return;
522
+ }
523
+ if (!validBrowserLiveControl(frame) || frame.action !== 'pointer' || frame.liveSessionId !== options.liveSessionId
524
+ || this.sessionOwned && (!this.viewerOptions || !this.viewerOptions.isAuthorized()))
525
+ throw new Error('browser_live_scope_invalid');
526
+ if (frame.controlEpoch !== this.controlEpoch || this.mode !== 'human' || !this.private)
527
+ return;
528
+ const input = decryptBrowserPointer(frame, options, options.identity);
529
+ await this.port.queue(async () => {
530
+ this.assertAuthorized(options);
531
+ if (frame.controlEpoch !== this.controlEpoch || this.mode !== 'human' || !this.private)
532
+ return;
533
+ const { page, tabId } = this.port.active();
534
+ const viewport = page.viewportSize();
535
+ try {
536
+ if (input.phase === 'down') {
537
+ for (const [id, expiresAt] of this.pointerStarts)
538
+ if (expiresAt <= Date.now())
539
+ this.pointerStarts.delete(id);
540
+ if (this.pointerStarts.has(input.gestureId) || this.pointerStarts.size >= 64)
541
+ return;
542
+ this.pointerStarts.set(input.gestureId, frame.privateInput.expiresAt);
543
+ await this.stopPointer();
544
+ this.port.observations.require(input.observationId, page, tabId, true);
545
+ if (!viewport || input.x >= viewport.width || input.y >= viewport.height)
546
+ return;
547
+ const pointer = { id: input.gestureId, page, tabId, url: page.url(), width: viewport.width, height: viewport.height,
548
+ navigation: () => { void this.stopPointer(); },
549
+ epoch: frame.controlEpoch, sequence: 0, button: input.button, modifiers: input.modifiers ?? [] };
550
+ this.pointer = pointer;
551
+ page.on('framenavigated', pointer.navigation);
552
+ for (const key of pointer.modifiers)
553
+ await page.keyboard.down(key);
554
+ await page.mouse.move(input.x, input.y);
555
+ this.assertAuthorized(options);
556
+ if (this.pointer !== pointer || this.controlEpoch !== pointer.epoch || this.mode !== 'human') {
557
+ await releasePageInput(page);
558
+ return;
559
+ }
560
+ await page.mouse.down({ button: pointer.button });
561
+ if (this.pointer !== pointer || this.controlEpoch !== pointer.epoch || this.mode !== 'human') {
562
+ await releasePageInput(page);
563
+ return;
564
+ }
565
+ }
566
+ else {
567
+ const pointer = this.pointer;
568
+ if (!pointer || pointer.id !== input.gestureId || input.sequence <= pointer.sequence)
569
+ return;
570
+ if (input.phase === 'cancel' || pointer.page !== page || pointer.tabId !== tabId || pointer.url !== page.url()
571
+ || viewport?.width !== pointer.width || viewport?.height !== pointer.height
572
+ || input.x >= viewport.width || input.y >= viewport.height) {
573
+ await this.stopPointer();
574
+ return;
575
+ }
576
+ pointer.sequence = input.sequence;
577
+ await page.mouse.move(input.x, input.y);
578
+ if (input.phase === 'up') {
579
+ await this.stopPointer(true);
580
+ return;
581
+ }
582
+ }
583
+ if (this.pointer) {
584
+ if (this.pointerExpiry)
585
+ clearTimeout(this.pointerExpiry);
586
+ this.pointerExpiry = setTimeout(() => { void this.stopPointer(); }, 10_000);
587
+ this.pointerExpiry.unref();
588
+ }
589
+ }
590
+ catch (error) {
591
+ await this.stopPointer();
592
+ if (!(error instanceof Error && error.message === 'browser_observation_stale'))
593
+ throw error;
594
+ }
595
+ }, true);
596
+ }
597
+ async copySelection(frame) {
598
+ const options = this.options;
599
+ this.assertAuthorized(options);
600
+ if (!validBrowserLiveControl(frame) || frame.action !== 'copy_selection' || frame.liveSessionId !== options.liveSessionId
601
+ || this.sessionOwned && (!this.viewerOptions || !this.viewerOptions.isAuthorized()))
602
+ throw new Error('browser_live_scope_invalid');
603
+ if (frame.controlEpoch !== this.controlEpoch || this.mode !== 'human' || !this.private)
604
+ return undefined;
605
+ const request = decryptClipboardRequest(frame, options, options.identity);
606
+ try {
607
+ return await this.port.queue(async () => {
608
+ this.assertAuthorized(options);
609
+ if (this.mode !== 'human' || this.controlEpoch !== frame.controlEpoch || !this.private)
610
+ return undefined;
611
+ const { page, tabId } = this.port.active();
612
+ try {
613
+ this.port.observations.require(request.observationId, page, tabId, true);
614
+ }
615
+ catch {
616
+ return undefined;
617
+ }
618
+ const url = page.url();
619
+ const selected = await readPageSelection(page);
620
+ this.assertAuthorized(options);
621
+ if (!selected || this.mode !== 'human' || this.controlEpoch !== frame.controlEpoch
622
+ || this.port.active().page !== page || page.url() !== url)
623
+ return undefined;
624
+ return encryptBrowserSelection(frame, request.key, selected);
625
+ }, true);
626
+ }
627
+ finally {
628
+ request.key.fill(0);
629
+ }
630
+ }
497
631
  async control(frame) {
498
632
  const options = this.options;
499
633
  let humanProfileTransition = false;
@@ -513,14 +647,16 @@ export class BrowserLiveHandle {
513
647
  if (this.requests.size >= 4096)
514
648
  throw new Error('browser_live_reconnect_required');
515
649
  this.requests.set(frame.requestId, Date.now());
516
- const transition = ['takeover', 'release', 'profile', 'select_tab'].includes(frame.action)
650
+ const transition = ['takeover', 'release', 'profile', 'select_tab', 'new_tab', 'close_tab', 'close_session'].includes(frame.action)
517
651
  || frame.action === 'stop' && this.mode !== 'observe';
518
652
  if (transition ? frame.controlEpoch !== this.controlEpoch + 1
519
653
  : frame.action === 'start' ? frame.controlEpoch > this.controlEpoch : frame.controlEpoch !== this.controlEpoch)
520
654
  throw new Error('browser_live_epoch_stale');
521
655
  const priorMode = this.mode;
656
+ if (this.port.control.tabId && ['profile', 'select_tab', 'new_tab', 'close_tab', 'close_session'].includes(frame.action))
657
+ throw new Error('browser_live_tab_scope_required');
522
658
  humanProfileTransition = frame.action === 'profile' && priorMode === 'human';
523
- if (['input', 'profile', 'select_tab', 'settings', 'navigate'].includes(frame.action) && priorMode !== 'human'
659
+ if (['input', 'profile', 'select_tab', 'new_tab', 'close_tab', 'settings', 'navigate'].includes(frame.action) && priorMode !== 'human'
524
660
  || frame.action === 'recording' && priorMode === 'blocked' && frame.recording?.mode !== 'off')
525
661
  throw new Error('browser_live_human_owner_required');
526
662
  if (frame.action === 'recording_save') {
@@ -531,27 +667,35 @@ export class BrowserLiveHandle {
531
667
  if (transition) {
532
668
  this.port.control.epoch = frame.controlEpoch;
533
669
  this.port.control.mode = 'blocked';
670
+ if (frame.action === 'takeover')
671
+ this.port.control.tabId = frame.tabId;
534
672
  this.port.observations.invalidate();
535
673
  }
536
674
  return await this.port.queue(async () => {
537
675
  this.assertAuthorized(options);
538
676
  if (frame.action !== 'start' && frame.controlEpoch !== this.controlEpoch)
539
677
  throw new Error('browser_live_epoch_stale');
678
+ if (this.pointer)
679
+ await this.stopPointer();
540
680
  if (frame.action === 'takeover') {
681
+ if (frame.tabId && this.port.active().tabId !== frame.tabId)
682
+ throw new Error('browser_tab_missing');
541
683
  this.port.control.private = frame.private !== false;
542
684
  if (this.private)
543
685
  await this.stopCapture();
544
- for (const page of this.port.pages())
686
+ for (const page of this.controlledPages())
545
687
  await releasePageInput(page);
546
688
  this.assertAuthorized(options);
547
689
  this.port.control.mode = 'human';
548
690
  }
549
691
  else if (frame.action === 'release') {
550
- await this.stopCapture();
692
+ if (this.private)
693
+ await this.stopCapture();
551
694
  this.assertAuthorized(options);
552
695
  await this.port.release();
553
696
  this.assertAuthorized(options);
554
697
  this.port.control.private = false;
698
+ this.port.control.mode = 'observe';
555
699
  }
556
700
  else if (frame.action === 'input') {
557
701
  const interaction = decryptBrowserHumanInput(frame, options, options.identity);
@@ -580,6 +724,20 @@ export class BrowserLiveHandle {
580
724
  this.assertAuthorized(options);
581
725
  this.port.control.mode = 'human';
582
726
  }
727
+ else if (frame.action === 'new_tab' || frame.action === 'close_tab' || frame.action === 'close_session') {
728
+ await this.stopCapture();
729
+ this.assertAuthorized(options);
730
+ if (frame.action === 'close_session') {
731
+ await this.port.closeSession();
732
+ return { ...ack(true), closed: true };
733
+ }
734
+ if (frame.action === 'close_tab' && await this.port.closeTab(frame.tabId))
735
+ return { ...ack(true), closed: true };
736
+ if (frame.action === 'new_tab')
737
+ await this.port.newTab();
738
+ this.assertAuthorized(options);
739
+ this.port.control.mode = 'human';
740
+ }
583
741
  else if (frame.action === 'settings') {
584
742
  await this.stopCapture();
585
743
  this.assertAuthorized(options);
@@ -656,18 +814,25 @@ export class BrowserLiveHandle {
656
814
  await this.refreshFrame();
657
815
  const state = await this.state();
658
816
  this.assertAuthorized(options);
659
- if (frame.action === 'release') {
660
- this.port.control.mode = 'observe';
661
- await this.stopCapture();
662
- await this.sync();
663
- }
664
- return ack(true, undefined, frame.action === 'release' ? await this.state() : state);
817
+ if (frame.action === 'release')
818
+ this.port.control.tabId = undefined;
819
+ return ack(true, undefined, state);
665
820
  });
666
821
  }
667
822
  catch (error) {
668
823
  const message = error instanceof Error && /^browser_[a-z_]+$/u.test(error.message) ? error.message : 'browser_live_control_failed';
669
824
  // Geometry may change during native smooth scrolling. This rejected action had no
670
825
  // side effects: refresh its observation without ending the user's control or replaying it.
826
+ if ((frame.action === 'new_tab' || frame.action === 'close_tab') && ['browser_tab_limit', 'browser_tab_missing'].includes(message)) {
827
+ try {
828
+ this.assertAuthorized(options);
829
+ this.port.control.mode = 'human';
830
+ await this.sync();
831
+ await this.refreshFrame(this.controlEpoch);
832
+ return ack(false, message, await this.state());
833
+ }
834
+ catch { /* Keep ordinary authorization failures fenced. */ }
835
+ }
671
836
  if (frame.action === 'recording' && ['browser_recording_private', 'browser_recording_network_required'].includes(message)) {
672
837
  try {
673
838
  this.assertAuthorized(options);
@@ -733,10 +898,21 @@ export class BrowserLiveHandle {
733
898
  this.port.control.mode = 'blocked';
734
899
  this.port.control.private = true;
735
900
  this.port.observations.invalidate();
901
+ void this.stopPointer();
736
902
  void this.stopCapture().catch(() => undefined);
737
- for (const page of this.port.pages())
903
+ for (const page of this.controlledPages())
738
904
  void releasePageInput(page);
739
905
  }
906
+ controlledPages() {
907
+ if (!this.port.control.tabId)
908
+ return this.port.pages();
909
+ try {
910
+ return [this.port.active().page];
911
+ }
912
+ catch {
913
+ return [];
914
+ }
915
+ }
740
916
  async settled() { await this.captureQueue.catch(() => undefined); }
741
917
  disconnect() {
742
918
  if (this.closed)
@@ -771,7 +947,7 @@ export class BrowserLiveHandle {
771
947
  if (this.poll)
772
948
  clearInterval(this.poll);
773
949
  void this.stopCapture().catch(() => undefined);
774
- for (const page of this.port.pages())
950
+ for (const page of this.controlledPages())
775
951
  void releasePageInput(page);
776
952
  }
777
953
  }
@@ -4,7 +4,7 @@ import type { BrowserObservation } from './terminal-browser-interaction.ts';
4
4
  export declare class BrowserObservations {
5
5
  private generation;
6
6
  private readonly entries;
7
- invalidate(): void;
7
+ invalidate(page?: Page): void;
8
8
  fresh(page: Page, tabId: string): BrowserObservation;
9
9
  require(id: string, page: Page, tabId: string, human?: boolean): BrowserObservation;
10
10
  }
@@ -3,7 +3,16 @@ import { randomUUID } from 'node:crypto';
3
3
  export class BrowserObservations {
4
4
  generation = 0;
5
5
  entries = new Map();
6
- invalidate() { this.generation++; this.entries.clear(); }
6
+ invalidate(page) {
7
+ if (page) {
8
+ for (const [id, observed] of this.entries)
9
+ if (observed.page === page)
10
+ this.entries.delete(id);
11
+ return;
12
+ }
13
+ this.generation++;
14
+ this.entries.clear();
15
+ }
7
16
  fresh(page, tabId) {
8
17
  const viewport = page.viewportSize();
9
18
  if (!viewport || page.isClosed())