@revoengine/cli 1.0.38 → 2.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 (47) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +22 -10
  3. package/dist/src/argument-contract.js +5 -5
  4. package/dist/src/automation-contract.generated.d.ts +6 -30
  5. package/dist/src/automation-contract.generated.js +6 -30
  6. package/dist/src/client.d.ts +2 -2
  7. package/dist/src/client.js +4 -14
  8. package/dist/src/commands/component.js +16 -0
  9. package/dist/src/commands/database-tables.js +1 -1
  10. package/dist/src/commands/emulate.js +67 -74
  11. package/dist/src/commands/terminal-browser-human-input.d.ts +28 -0
  12. package/dist/src/commands/terminal-browser-human-input.js +56 -7
  13. package/dist/src/commands/terminal-browser-live-protocol.d.ts +13 -1
  14. package/dist/src/commands/terminal-browser-live-protocol.js +20 -4
  15. package/dist/src/commands/terminal-browser-live-transport.d.ts +2 -0
  16. package/dist/src/commands/terminal-browser-live-transport.js +21 -4
  17. package/dist/src/commands/terminal-browser-live.d.ts +36 -1
  18. package/dist/src/commands/terminal-browser-live.js +435 -106
  19. package/dist/src/commands/terminal-browser-observation.d.ts +1 -1
  20. package/dist/src/commands/terminal-browser-observation.js +10 -1
  21. package/dist/src/commands/terminal-browser-page-input.d.ts +1 -0
  22. package/dist/src/commands/terminal-browser-page-input.js +20 -0
  23. package/dist/src/commands/terminal-browser-profile-sync.d.ts +5 -1
  24. package/dist/src/commands/terminal-browser-profile-sync.js +13 -2
  25. package/dist/src/commands/terminal-browser-profile-sync.protocol.d.ts +2 -0
  26. package/dist/src/commands/terminal-browser-recording.d.ts +6 -3
  27. package/dist/src/commands/terminal-browser-recording.js +45 -15
  28. package/dist/src/commands/terminal-browser.d.ts +17 -0
  29. package/dist/src/commands/terminal-browser.js +318 -111
  30. package/dist/src/commands/terminal-operational-log.js +2 -1
  31. package/dist/src/commands/terminal-output-buffer.d.ts +2 -0
  32. package/dist/src/commands/terminal-output-buffer.js +6 -0
  33. package/dist/src/commands/terminal-reconnect-grace.d.ts +1 -0
  34. package/dist/src/commands/terminal-reconnect-grace.js +1 -0
  35. package/dist/src/commands/terminal-sandbox.js +22 -6
  36. package/dist/src/commands/terminal.js +136 -40
  37. package/dist/src/endpoint-emulator.d.ts +16 -13
  38. package/dist/src/endpoint-emulator.js +26 -35
  39. package/dist/src/project.js +1 -0
  40. package/dist/src/request-contract.d.ts +2 -0
  41. package/dist/src/request-contract.js +11 -1
  42. package/dist/src/resource-syncs/database-table-sync.d.ts +2 -1
  43. package/dist/src/resource-syncs/database-table-sync.js +60 -23
  44. package/dist/src/sync-omit.js +1 -1
  45. package/dist/src/types.d.ts +0 -3
  46. package/dist/src/ui.js +2 -2
  47. package/package.json +1 -1
@@ -3,9 +3,7 @@ import { realpath } from 'node:fs/promises';
3
3
  import path from 'node:path';
4
4
  import { createEndpointEmulator, assertEmulatorWorkspace, DEFAULT_EMULATOR_HOST, isLoopbackEmulatorHost, normalizeEmulatorHost, } from "../endpoint-emulator.js";
5
5
  import { buildSandboxDebugUrl, extractSandboxEndpoint, extractServiceEndpoint, readProjectStableKeyName, REVO_PROJECT_DIR } from "../project.js";
6
- import { readConfiguredResourceMetadataStableKey } from "../resource-metadata.js";
7
6
  import { resolveAuthenticatedInstance } from "../resource-target.js";
8
- import { portableExecutionPolicy, SYSTEM_ACCOUNT_ID } from "../resource-syncs/account-principal.js";
9
7
  import { requireProjectLayout } from "../resource-syncs/util.js";
10
8
  import { writeJsonFile } from "../utils.js";
11
9
  function formatRequestEvent(event, json) {
@@ -13,7 +11,7 @@ function formatRequestEvent(event, json) {
13
11
  if (json) {
14
12
  const request = { time, event: event.event, id: event.id, method: event.method };
15
13
  return JSON.stringify(event.event === 'request_started' ? request : {
16
- ...request, durationMs: event.durationMs,
14
+ ...request, durationMs: event.durationMs, execution: event.execution,
17
15
  ...(event.event === 'request_finished' ? { status: event.status } : {}),
18
16
  });
19
17
  }
@@ -21,27 +19,27 @@ function formatRequestEvent(event, json) {
21
19
  if (event.event === 'request_started')
22
20
  return `${request} received`;
23
21
  const status = event.event === 'request_finished' ? event.status : 'aborted';
24
- return `${request} → ${status} (${event.durationMs} ms)`;
22
+ const execution = event.execution === 'published' ? ' · Published Run'
23
+ : event.execution === 'sandbox' ? ' · Sandbox preview' : '';
24
+ return `${request} → ${status} (${event.durationMs} ms)${execution}`;
25
25
  }
26
26
  export async function handleEmulateCommand(context) {
27
27
  if (context.args._[1] !== 'endpoints' || context.args._.length !== 2) {
28
- throw new Error('Usage: revo emulate endpoints --read-only=true|false [--project <name>] [--host <address>] [--port <port>] [--service-account=caller|published] [--no-watch]');
29
- }
30
- const mode = context.args['read-only'];
31
- if (mode !== 'true' && mode !== 'false') {
32
- throw new Error('Pass --read-only=true or --read-only=false explicitly.');
33
- }
34
- const readOnly = mode === 'true';
35
- const serviceAccountMode = context.args['service-account'] ?? 'reject';
36
- if (!['reject', 'caller', 'published'].includes(String(serviceAccountMode))) {
37
- throw new Error('--service-account must be caller or published.');
38
- }
39
- if (serviceAccountMode === 'published' && readOnly) {
40
- throw new Error('--service-account=published requires --read-only=false because normal Run execution can write.');
28
+ throw new Error('Usage: revo emulate endpoints [--mode=local|published] [--read-only=true|false] [--project <name>] [--host <address>] [--port <port>] [--skip-validate] [--no-watch]');
41
29
  }
30
+ const readOnly = context.args['read-only'] !== 'false';
31
+ const mode = context.args.mode ?? 'local';
32
+ if (mode !== 'local' && mode !== 'published')
33
+ throw new Error('--mode must be local or published.');
34
+ const skipValidate = context.args['skip-validate'] === true;
42
35
  const host = normalizeEmulatorHost(String(context.args.host ?? DEFAULT_EMULATOR_HOST));
43
- if (serviceAccountMode === 'published' && !isLoopbackEmulatorHost(host)) {
44
- throw new Error('--service-account=published requires a loopback host.');
36
+ if (mode === 'published') {
37
+ if (readOnly)
38
+ throw new Error('--mode=published requires --read-only=false because Run can write.');
39
+ if (!isLoopbackEmulatorHost(host))
40
+ throw new Error('--mode=published requires a loopback host.');
41
+ if (skipValidate)
42
+ throw new Error('--skip-validate applies to local preview.');
45
43
  }
46
44
  const portValue = String(context.args.port ?? 4300);
47
45
  const port = Number(portValue);
@@ -49,13 +47,7 @@ export async function handleEmulateCommand(context) {
49
47
  throw new Error('--port must be an integer from 1 to 65535.');
50
48
  }
51
49
  const layout = requireProjectLayout(context.cwd, 'Endpoint emulator');
52
- const [projectRoot, workspaceRoot] = await Promise.all([realpath(layout.projectRoot), realpath(layout.workspaceRoot)]);
53
- const relative = path.relative(projectRoot, workspaceRoot);
54
- if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
55
- throw new Error('Endpoint emulator workspace must stay inside the Revo project.');
56
- }
57
- const stableKeyName = readProjectStableKeyName(projectRoot);
58
- await assertEmulatorWorkspace(workspaceRoot);
50
+ const projectRoot = await realpath(layout.projectRoot);
59
51
  let profile;
60
52
  try {
61
53
  await resolveAuthenticatedInstance(context.client, 'target');
@@ -64,58 +56,56 @@ export async function handleEmulateCommand(context) {
64
56
  catch {
65
57
  throw new Error('Could not validate the selected CLI project. Check authentication and project settings.');
66
58
  }
67
- const sandbox = extractSandboxEndpoint(profile);
68
- if (!sandbox)
69
- throw new Error('The authenticated project did not advertise a sandbox endpoint.');
70
- const sandboxUrl = buildSandboxDebugUrl(sandbox);
71
- const run = serviceAccountMode === 'published' ? extractServiceEndpoint(profile, 'run') : null;
72
- if (serviceAccountMode === 'published' && !run) {
73
- throw new Error('The authenticated project did not advertise a Run endpoint.');
74
- }
75
59
  const json = context.args.json === true;
76
60
  const watch = context.args.watch === undefined ? !json : context.args.watch === true;
77
- const server = createEndpointEmulator({
78
- workspaceRoot,
79
- stableKeyName,
61
+ const listenerOptions = {
80
62
  host,
81
- readOnly,
82
- serviceAccountAsCaller: serviceAccountMode === 'caller',
83
- ...(run ? { runPublishedEndpoint: async ({ endpoint, url, headers, body, signal }) => {
84
- const remote = await context.client.findPublishedEndpoint(endpoint.route.method, endpoint.route.path, signal);
85
- const policy = remote?.executionPolicy;
86
- const local = endpoint.executionPolicy;
87
- const mismatch = { status: 409, body: { code: 'PUBLISHED_ENDPOINT_MISMATCH',
88
- message: 'The active published endpoint does not match the local route, Stable Key and service-account policy.' } };
89
- if (!remote?.active || remote.deletedAt || remote.deletedBy || remote.method !== endpoint.route.method
90
- || remote.path !== endpoint.route.path || readConfiguredResourceMetadataStableKey(remote, stableKeyName) !== endpoint.stableKey
91
- || policy?.mode !== 'SERVICE_ACCOUNT' || (local.currentUser && policy.currentUser !== local.currentUser))
92
- return mismatch;
93
- if (remote.options?.responseMode === 'sse') {
94
- return { status: 501, body: { code: 'ENDPOINT_OPTIONS_UNSUPPORTED', message: 'Published SSE endpoints are unavailable in the emulator.' } };
95
- }
96
- if (local.serviceAccount?.kind === 'system') {
97
- if (policy.serviceAccountUserId !== SYSTEM_ACCOUNT_ID)
98
- return mismatch;
99
- }
100
- else {
101
- const published = await portableExecutionPolicy(context.client, policy, stableKeyName);
102
- if (published?.serviceAccount?.kind !== 'service-account'
103
- || published.serviceAccount.stableKey !== local.serviceAccount?.stableKey)
104
- return mismatch;
105
- }
63
+ ...(watch ? { onRequest: (event) => context.println(formatRequestEvent(event, json)) } : {}),
64
+ };
65
+ let server;
66
+ if (mode === 'published') {
67
+ const run = extractServiceEndpoint(profile, 'run');
68
+ if (!run)
69
+ throw new Error('The authenticated project did not advertise a Run endpoint.');
70
+ server = createEndpointEmulator({
71
+ ...listenerOptions,
72
+ runPublishedEndpoint: async ({ method, url, headers, body, signal }) => {
106
73
  const upstream = new URL(run);
107
74
  upstream.pathname = upstream.pathname.replace(/\/+$/, '') + url.pathname;
108
75
  upstream.search = url.search;
109
76
  upstream.hash = '';
110
- const result = await context.client.request(endpoint.route.method, upstream.toString(), {
77
+ const result = await context.client.request(method, upstream.toString(), {
111
78
  headers, body, signal, allowExternalOrigin: true, publishedRun: true, maxRetries: 0,
112
- spinnerLabel: false, timeoutMs: (remote.timeout ?? endpoint.timeout ?? 60) * 1000 + 15_000,
79
+ spinnerLabel: false, timeoutMs: 75_000,
113
80
  });
81
+ if (result.data === undefined) {
82
+ return { status: 501, body: { code: 'ENDPOINT_OPTIONS_UNSUPPORTED',
83
+ message: 'Published SSE endpoints are unavailable in the emulator.' } };
84
+ }
114
85
  return { status: result.status, body: result.data, headers: result.headers };
115
- } } : {}),
116
- ...(watch ? { onRequest: (event) => context.println(formatRequestEvent(event, json)) } : {}),
117
- debug: (payload, signal, timeoutMs) => context.client.debugComponent(sandboxUrl, payload, { signal, timeoutMs, maxRetries: 0, spinnerLabel: false }),
118
- });
86
+ },
87
+ });
88
+ }
89
+ else {
90
+ const workspaceRoot = await realpath(layout.workspaceRoot);
91
+ const relative = path.relative(projectRoot, workspaceRoot);
92
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
93
+ throw new Error('Endpoint emulator workspace must stay inside the Revo project.');
94
+ }
95
+ await assertEmulatorWorkspace(workspaceRoot);
96
+ const sandbox = extractSandboxEndpoint(profile);
97
+ if (!sandbox)
98
+ throw new Error('The authenticated project did not advertise a sandbox endpoint.');
99
+ const sandboxUrl = buildSandboxDebugUrl(sandbox);
100
+ server = createEndpointEmulator({
101
+ ...listenerOptions,
102
+ workspaceRoot,
103
+ stableKeyName: readProjectStableKeyName(projectRoot),
104
+ readOnly,
105
+ skipValidate,
106
+ debug: (payload, signal, timeoutMs) => context.client.debugComponent(sandboxUrl, payload, { signal, timeoutMs, maxRetries: 0, spinnerLabel: false }),
107
+ });
108
+ }
119
109
  const stop = () => {
120
110
  server.close();
121
111
  server.closeAllConnections();
@@ -147,22 +137,25 @@ export async function handleEmulateCommand(context) {
147
137
  throw new Error('Could not save the endpoint emulator settings. Check the local project configuration directory.');
148
138
  }
149
139
  if (json) {
150
- context.println(JSON.stringify({ event: 'ready', port, localOnly, readOnly, serviceAccountMode }));
140
+ context.println(JSON.stringify({ event: 'ready', port, localOnly, readOnly, mode,
141
+ ...(skipValidate ? { skipValidate } : {}) }));
151
142
  }
152
143
  else {
153
144
  context.println(`Endpoint emulator listening on port ${port} (${localOnly ? 'local only' : 'network access'}, readOnly: ${readOnly}).`);
154
- if (serviceAccountMode === 'caller')
155
- context.println('Service-account endpoints with a caller identity run under your CLI account in this session.');
156
- if (serviceAccountMode === 'published')
157
- context.println('Service-account endpoints execute the active published definition in RevoEngine Run.');
145
+ context.println(mode === 'local' ? 'Local changes run in Sandbox under your CLI identity.'
146
+ : 'Published endpoints run in RevoEngine Run under their published execution policy.');
158
147
  if (host === '0.0.0.0' || host === '::')
159
148
  context.println('Connect from another device using this machine’s network IP address.');
160
149
  if (!isLoopbackEmulatorHost(host)) {
161
150
  context.println('Clients that can reach this port can invoke endpoints using the CLI project credentials. Use a trusted network.');
162
151
  }
152
+ if (skipValidate)
153
+ context.println('Sandbox preview skips low-code source analysis.');
163
154
  if (watch)
164
155
  context.println('Watching HTTP requests.');
165
- context.println('Save local manifests or source files to use them on the next request. Press Ctrl+C to stop.');
156
+ if (mode === 'local')
157
+ context.println('Save local manifests or source files to use them on the next request.');
158
+ context.println('Press Ctrl+C to stop.');
166
159
  }
167
160
  await closed;
168
161
  }
@@ -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' | '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;
@@ -159,6 +167,10 @@ export declare function safeBrowserLiveState(value: any): {
159
167
  height: any;
160
168
  } | undefined;
161
169
  recordingState: {
170
+ checkpoint?: {
171
+ recordingId: any;
172
+ status: any;
173
+ } | undefined;
162
174
  status: any;
163
175
  elapsedMs: any;
164
176
  } | undefined;
@@ -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', '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,
@@ -174,7 +187,10 @@ export function safeBrowserLiveState(value) {
174
187
  ? { fps: value.settings.fps, width: value.settings.width, height: value.settings.height } : undefined,
175
188
  recordingState: value?.recordingState && ['off', 'recording', 'paused'].includes(value.recordingState.status)
176
189
  && integer(value.recordingState.elapsedMs, 0, Number.MAX_SAFE_INTEGER)
177
- ? { status: value.recordingState.status, elapsedMs: value.recordingState.elapsedMs } : undefined,
190
+ ? { status: value.recordingState.status, elapsedMs: value.recordingState.elapsedMs,
191
+ ...(validLiveId(value.recordingState.checkpoint?.recordingId)
192
+ && ['saving', 'saved', 'failed'].includes(value.recordingState.checkpoint?.status)
193
+ ? { checkpoint: { recordingId: value.recordingState.checkpoint.recordingId, status: value.recordingState.checkpoint.status } } : {}) } : undefined,
178
194
  focusEditable: value?.focusEditable === true, focusId: validLiveId(value?.focusId) ? value.focusId : undefined, pageUrl, frameSequence };
179
195
  }
180
196
  export function safeBrowserScreenshotTransform(value) {
@@ -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,12 +121,29 @@ export class TerminalBrowserLiveTransport {
120
121
  return;
121
122
  }
122
123
  if (message.type === 'browser_live_control') {
123
- mediaReady = false;
124
- controlInFlight = true;
125
124
  if (message.connectionId !== frame.connectionId || message.browserSessionId !== frame.browserSessionId
126
125
  || message.actorUserId !== frame.actorUserId || message.threadId !== frame.threadId
127
126
  || message.agentTerminalWorkspaceId !== frame.agentTerminalWorkspaceId)
128
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;
129
147
  if (!handle) {
130
148
  if (message.action !== 'start' || message.controlEpoch !== frame.controlEpoch)
131
149
  throw new Error('browser_live_scope_invalid');
@@ -155,10 +173,9 @@ export class TerminalBrowserLiveTransport {
155
173
  return;
156
174
  }
157
175
  }
158
- const control = Object.fromEntries(Object.entries(message).filter(([key]) => ['type', 'protocol', 'requestId',
159
- 'liveSessionId', 'controlEpoch', 'action', 'private', 'privateInput', 'profile', 'recording', 'tabId', 'settings', 'navigation'].includes(key)));
160
176
  send(await handle.control(control));
161
177
  controlInFlight = false;
178
+ this.options.onInventoryChanged?.();
162
179
  return;
163
180
  }
164
181
  if (message.type === 'browser_recording_upload') {
@@ -10,6 +10,11 @@ export type BrowserLiveRecording = {
10
10
  size: number;
11
11
  name: string;
12
12
  mode: 'local' | 'storage' | 'both';
13
+ checkpoint?: boolean;
14
+ };
15
+ export type BrowserRecordingCheckpoint = {
16
+ recordingId: string;
17
+ status: 'saving' | 'saved' | 'failed';
13
18
  };
14
19
  export type BrowserLiveOptions = HumanInputScope & {
15
20
  liveSessionId: string;
@@ -28,11 +33,13 @@ export type BrowserLiveOptions = HumanInputScope & {
28
33
  controlEpoch: number;
29
34
  mode: BrowserLiveMode;
30
35
  private: boolean;
36
+ tabId?: string;
31
37
  };
32
38
  recordingDirectory: string;
33
39
  isAuthorized: () => boolean;
34
40
  onFrame: (frame: Buffer) => void;
35
41
  onRecording: (recording: BrowserLiveRecording) => boolean | void;
42
+ recordingCheckpoint?: () => BrowserRecordingCheckpoint | undefined;
36
43
  onFailure?: (code: string, controlEpoch: number) => void;
37
44
  onState?: (update: {
38
45
  controlEpoch: number;
@@ -46,6 +53,7 @@ export type BrowserLivePort = {
46
53
  mode: BrowserLiveMode;
47
54
  private: boolean;
48
55
  connected: boolean;
56
+ tabId?: string;
49
57
  };
50
58
  observations: BrowserObservations;
51
59
  active: () => {
@@ -53,11 +61,14 @@ export type BrowserLivePort = {
53
61
  tabId: string;
54
62
  };
55
63
  pages: () => Page[];
56
- queue: <T>(work: () => Promise<T>) => Promise<T>;
64
+ queue: <T>(work: () => Promise<T>, tabInput?: boolean) => Promise<T>;
57
65
  state: () => Promise<Record<string, unknown>>;
58
66
  authorized: () => boolean;
59
67
  fullNetwork: () => boolean;
60
68
  selectTab: (tabId: string) => Promise<void>;
69
+ newTab: () => Promise<void>;
70
+ closeTab: (tabId: string) => Promise<boolean>;
71
+ closeSession: () => Promise<void>;
61
72
  release: () => Promise<void>;
62
73
  profile: (profile: NonNullable<BrowserLiveControl['profile']>, options: BrowserLiveOptions) => Promise<void>;
63
74
  };
@@ -70,6 +81,7 @@ export type BrowserLiveAck = {
70
81
  ok: boolean;
71
82
  error?: string;
72
83
  state?: Record<string, unknown>;
84
+ closed?: true;
73
85
  };
74
86
  /** Reads SOF JPEG dimensions without decoding or allocating an image. */
75
87
  export declare function jpegDimensions(jpeg: Buffer): {
@@ -78,6 +90,9 @@ export declare function jpegDimensions(jpeg: Buffer): {
78
90
  };
79
91
  export declare function browserAuthPage(value: string): boolean;
80
92
  export declare class BrowserLiveHandle {
93
+ private pointer?;
94
+ private pointerExpiry?;
95
+ private readonly pointerStarts;
81
96
  private baseOptions;
82
97
  private viewerOptions?;
83
98
  private get options();
@@ -87,7 +102,10 @@ export declare class BrowserLiveHandle {
87
102
  resumeRecordingIfPublic(): Promise<void>;
88
103
  private readonly port;
89
104
  private page?;
105
+ private preview?;
90
106
  private segment?;
107
+ private recordingStop?;
108
+ private pendingCheckpoint?;
91
109
  private recordingMode;
92
110
  private fps;
93
111
  private settingsApplied;
@@ -113,22 +131,39 @@ export declare class BrowserLiveHandle {
113
131
  get private(): boolean;
114
132
  private assertAuthorized;
115
133
  state(): Promise<Record<string, unknown>>;
134
+ private recordingState;
116
135
  start(): Promise<void>;
117
136
  private captureQueue;
118
137
  private capture;
119
138
  private stopCapture;
120
139
  private stopCaptureInner;
140
+ private stopEncoder;
141
+ private finishRecording;
121
142
  pauseRecording(restartPreview?: boolean): Promise<void>;
122
143
  private syncing?;
123
144
  private sync;
124
145
  private publishCurrentState;
125
146
  private syncInner;
147
+ private prepareRecording;
148
+ private startRecording;
149
+ private startPreview;
150
+ private stopPreview;
151
+ private previewFrame;
126
152
  private cancelTrailingFrame;
127
153
  private scheduleTrailingFrame;
128
154
  private emitFrame;
129
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>;
130
163
  control(frame: BrowserLiveControl): Promise<BrowserLiveAck>;
164
+ private requestRecordingSave;
131
165
  block(epoch?: number): void;
166
+ private controlledPages;
132
167
  settled(): Promise<void>;
133
168
  disconnect(): void;
134
169
  close(): void;