@revoengine/cli 1.0.15 → 1.0.16

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 (49) hide show
  1. package/README.md +45 -9
  2. package/dist/src/cli.js +5 -1
  3. package/dist/src/client.d.ts +25 -3
  4. package/dist/src/client.js +67 -2
  5. package/dist/src/commands/component.js +1 -0
  6. package/dist/src/commands/index.d.ts +1 -0
  7. package/dist/src/commands/index.js +1 -0
  8. package/dist/src/commands/migrate.js +12 -2
  9. package/dist/src/commands/service-accounts.d.ts +2 -0
  10. package/dist/src/commands/service-accounts.js +149 -0
  11. package/dist/src/commands/terminal-browser.d.ts +29 -2
  12. package/dist/src/commands/terminal-browser.js +144 -35
  13. package/dist/src/commands/terminal-file.d.ts +21 -0
  14. package/dist/src/commands/terminal-file.js +160 -0
  15. package/dist/src/commands/terminal-operational-log.js +2 -2
  16. package/dist/src/commands/terminal-policy.d.ts +5 -2
  17. package/dist/src/commands/terminal-policy.js +10 -4
  18. package/dist/src/commands/terminal-reconnect-grace.js +1 -1
  19. package/dist/src/commands/terminal-sandbox.js +7 -0
  20. package/dist/src/commands/terminal-secure-browser.d.ts +1 -0
  21. package/dist/src/commands/terminal-secure-browser.js +2 -1
  22. package/dist/src/commands/terminal-service.js +4 -4
  23. package/dist/src/commands/terminal.d.ts +12 -0
  24. package/dist/src/commands/terminal.js +134 -45
  25. package/dist/src/component-lock.d.ts +4 -0
  26. package/dist/src/component-lock.js +21 -2
  27. package/dist/src/metadata-backfill.js +50 -1
  28. package/dist/src/migration.d.ts +10 -2
  29. package/dist/src/migration.js +159 -68
  30. package/dist/src/resource-inventory.d.ts +3 -2
  31. package/dist/src/resource-inventory.js +6 -1
  32. package/dist/src/resource-syncs/account-principal.d.ts +22 -0
  33. package/dist/src/resource-syncs/account-principal.js +86 -0
  34. package/dist/src/resource-syncs/group-sync.d.ts +10 -0
  35. package/dist/src/resource-syncs/group-sync.js +92 -20
  36. package/dist/src/resource-syncs/identity-migration.d.ts +19 -0
  37. package/dist/src/resource-syncs/identity-migration.js +108 -0
  38. package/dist/src/resource-syncs/job-template-sync.d.ts +4 -0
  39. package/dist/src/resource-syncs/job-template-sync.js +55 -12
  40. package/dist/src/resource-syncs/service-account-sync.d.ts +98 -0
  41. package/dist/src/resource-syncs/service-account-sync.js +620 -0
  42. package/dist/src/sync-output.js +3 -0
  43. package/dist/src/tracked-resources.d.ts +1 -1
  44. package/dist/src/tracked-resources.js +5 -1
  45. package/dist/src/types.d.ts +12 -0
  46. package/dist/src/ui.js +4 -1
  47. package/dist/src/workspace-diff.d.ts +1 -0
  48. package/dist/src/workspace-diff.js +4 -1
  49. package/package.json +2 -2
@@ -18,13 +18,14 @@ export function createSecureBrowserIdentity() {
18
18
  export function secureBrowserInputAad(frame) {
19
19
  return Buffer.from(JSON.stringify([frame.requestId, frame.threadId, frame.agentTerminalId,
20
20
  frame.browserSessionId, frame.origin, frame.selector, frame.connectionId,
21
- frame.keyId, frame.expiresAt]), 'utf8');
21
+ frame.keyId, frame.expiresAt, ...(frame.browserTabId ? [frame.browserTabId] : [])]), 'utf8');
22
22
  }
23
23
  export function decryptSecureBrowserInput(frame, identity) {
24
24
  if (frame.keyId !== identity.keyId || !Number.isSafeInteger(frame.expiresAt)
25
25
  || frame.expiresAt < Date.now() || frame.expiresAt > Date.now() + 120_000
26
26
  || !/^[a-f0-9-]{36}$/iu.test(frame.requestId)
27
27
  || !/^[a-f0-9]{64}$/u.test(frame.browserSessionId)
28
+ || frame.browserTabId !== undefined && !/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/iu.test(frame.browserTabId)
28
29
  || typeof frame.selector !== 'string' || !frame.selector.trim() || frame.selector.length > 500
29
30
  || typeof frame.origin !== 'string' || frame.origin.length > 2_048
30
31
  || typeof frame.threadId !== 'string' || frame.threadId.length > 128
@@ -43,14 +43,14 @@ export function renderTerminalSystemdUnit(options) {
43
43
  const entrypoint = options.entrypoint || (process.argv[1] && fs.realpathSync(process.argv[1]));
44
44
  if (!entrypoint || !path.isAbsolute(node) || !path.isAbsolute(entrypoint))
45
45
  throw new Error('Cannot resolve absolute Node.js and revo executable paths for systemd.');
46
- const args = [node, entrypoint, 'terminal', 'connect', '--workspace', options.workspace,
46
+ const args = [node, entrypoint, 'terminal', 'connect', '--service-runner', '--workspace', options.workspace,
47
47
  '--project', options.envName || 'default',
48
48
  ...(options.terminalId ? ['--terminal-id', options.terminalId] : [])];
49
49
  const env = [
50
50
  ...(options.pathValue ? [`Environment=${systemdQuote(`PATH=${options.pathValue}`)}`] : []),
51
51
  ...(options.configHome ? [`Environment=${systemdQuote(`XDG_CONFIG_HOME=${options.configHome}`)}`] : []),
52
52
  ];
53
- return `[Unit]\nDescription=RevoEngine Agent Terminal\n\n[Service]\nType=simple\nExecStart=${args.map(arg => systemdQuote(arg, true)).join(' ')}\nRestart=always\nRestartSec=30s\n${env.join('\n')}${env.length ? '\n' : ''}UnsetEnvironment=${AUTH_ENV_KEYS.join(' ')}\n\n[Install]\nWantedBy=default.target\n`;
53
+ return `[Unit]\nDescription=RevoEngine Agent Terminal\n\n[Service]\nType=simple\nExecStart=${args.map(arg => systemdQuote(arg, true)).join(' ')}\nRestart=on-failure\nRestartSec=30s\n${env.join('\n')}${env.length ? '\n' : ''}UnsetEnvironment=${AUTH_ENV_KEYS.join(' ')}\n\n[Install]\nWantedBy=default.target\n`;
54
54
  }
55
55
  export function renderTerminalServicePlist(options) {
56
56
  const paths = terminalServicePaths(options.workspace, options.envName, options.home, options.terminalId);
@@ -58,7 +58,7 @@ export function renderTerminalServicePlist(options) {
58
58
  const entrypoint = options.entrypoint || (process.argv[1] && fs.realpathSync(process.argv[1]));
59
59
  if (!entrypoint || !path.isAbsolute(node) || !path.isAbsolute(entrypoint))
60
60
  throw new Error('Cannot resolve absolute Node.js and revo executable paths for LaunchAgent.');
61
- const args = [node, entrypoint, 'terminal', 'connect', '--workspace', options.workspace,
61
+ const args = [node, entrypoint, 'terminal', 'connect', '--service-runner', '--workspace', options.workspace,
62
62
  '--project', options.envName || 'default',
63
63
  ...(options.terminalId ? ['--terminal-id', options.terminalId] : [])];
64
64
  const lines = args.map(arg => ` <string>${xml(arg)}</string>`).join('\n');
@@ -69,7 +69,7 @@ export function renderTerminalServicePlist(options) {
69
69
  env.push(` <key>XDG_CONFIG_HOME</key><string>${xml(options.configHome)}</string>`);
70
70
  for (const key of AUTH_ENV_KEYS)
71
71
  env.push(` <key>${key}</key><string></string>`);
72
- return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n <key>Label</key><string>${xml(paths.label)}</string>\n <key>ProgramArguments</key>\n <array>\n${lines}\n </array>\n <key>RunAtLoad</key><true/>\n <key>KeepAlive</key><true/>\n <key>ThrottleInterval</key><integer>30</integer>\n <key>StandardOutPath</key><string>${xml(paths.stdout)}</string>\n <key>StandardErrorPath</key><string>${xml(paths.stderr)}</string>\n <key>EnvironmentVariables</key>\n <dict>\n${env.join('\n')}\n </dict>\n</dict>\n</plist>\n`;
72
+ return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n <key>Label</key><string>${xml(paths.label)}</string>\n <key>ProgramArguments</key>\n <array>\n${lines}\n </array>\n <key>RunAtLoad</key><true/>\n <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n <key>ThrottleInterval</key><integer>30</integer>\n <key>StandardOutPath</key><string>${xml(paths.stdout)}</string>\n <key>StandardErrorPath</key><string>${xml(paths.stderr)}</string>\n <key>EnvironmentVariables</key>\n <dict>\n${env.join('\n')}\n </dict>\n</dict>\n</plist>\n`;
73
73
  }
74
74
  function ensureMac(options) {
75
75
  if ((options.platform || process.platform) !== 'darwin')
@@ -4,6 +4,15 @@ type TerminalGrant = {
4
4
  agentTerminalId: string;
5
5
  name?: string;
6
6
  workspace?: string;
7
+ workspaces?: Array<{
8
+ agentTerminalWorkspaceId: string;
9
+ path: string;
10
+ status: 'pending' | 'approved';
11
+ }>;
12
+ revision?: number;
13
+ connectionRevision?: number;
14
+ online?: boolean;
15
+ lastOnlineAt?: string | null;
7
16
  status: 'pending' | 'approved' | 'revoked';
8
17
  mode: 'review' | 'full';
9
18
  networkMode?: 'restricted' | 'sandbox' | 'external';
@@ -18,6 +27,7 @@ type CommandResult = {
18
27
  exitCode: number | null;
19
28
  stdout: string;
20
29
  stderr: string;
30
+ signal?: NodeJS.Signals;
21
31
  timedOut: boolean;
22
32
  truncated: boolean;
23
33
  logTruncated: boolean;
@@ -41,6 +51,7 @@ export declare function runCommand(input: {
41
51
  workdir: string;
42
52
  workspace: string;
43
53
  timeoutMs: number;
54
+ background?: boolean;
44
55
  sandbox?: TerminalSandbox;
45
56
  networkAccess?: TerminalNetworkAccess;
46
57
  policyDeadlineMs?: number | null;
@@ -64,5 +75,6 @@ export declare function runWorkspacePatch(input: {
64
75
  }) => void): ChildProcess & {
65
76
  updatePolicyDeadline: (deadline: number | null) => void;
66
77
  };
78
+ /** Supervisors retry crashes, but a revoked grant or 401/403 needs a human credential/grant change. */
67
79
  export declare function handleTerminalCommand(argv: string[]): Promise<void>;
68
80
  export {};
@@ -9,12 +9,15 @@ import { getActiveEnvironmentName, getConfigDir, getEnvironmentProfile, loadStor
9
9
  import { installTerminalService, terminalServiceInstalled, uninstallTerminalService } from "./terminal-service.js";
10
10
  import { createSandboxScratchDirectory, isTerminalSandbox, sandboxCommand, shellQuote, requiresElevatedCommand } from "./terminal-sandbox.js";
11
11
  import { executionAllowedByGrant, executionPolicyDeadline, remainingPolicyDeadline, validateExecutePolicy } from "./terminal-policy.js";
12
- import { closeBrowserSessions, fillBrowserSecret, hasBrowserSessions, reconcileBrowserSessions, runBrowserAction, validateBrowserActionInput } from "./terminal-browser.js";
12
+ import { closeThreadBrowserSession, threadBrowserScopes, browserSessionIds, closeBrowserSessions, fillBrowserSecret, hasBrowserSessions, reconcileBrowserSessions, runBrowserAction, validateBrowserActionInput } from "./terminal-browser.js";
13
+ import { transferWorkspaceFile, validateFileTransfer } from "./terminal-file.js";
13
14
  import { uploadWorkspaceImages } from "./terminal-image.js";
14
15
  import { ensurePtyHelperExecutable, normalizePtyStartError } from "./terminal-pty.js";
15
16
  import { TerminalReconnectGrace, TerminalTransportRecovery, isRunnerTransportHeartbeat } from "./terminal-reconnect-grace.js";
16
17
  import { TerminalOperationalLog } from "./terminal-operational-log.js";
17
18
  import { createSecureBrowserIdentity, decryptSecureBrowserInput } from "./terminal-secure-browser.js";
19
+ class TerminalRunnerFatalError extends Error {
20
+ }
18
21
  export function selectRegisteredTerminal(devices, grants, name, terminalId) {
19
22
  const matching = devices.filter(device => terminalId
20
23
  ? device.agentTerminalId === terminalId : device.name === name);
@@ -56,7 +59,8 @@ const LOG_RETENTION_MS = 24 * 60 * 60 * 1_000;
56
59
  const OPERATIONAL_ERROR_CODES = new Set([
57
60
  'browser_binary_unavailable', 'browser_cancelled', 'browser_failed', 'browser_localhost_only',
58
61
  'browser_local_network_guard_unavailable',
59
- 'browser_session_missing', 'browser_session_limit', 'browser_selector_missing', 'browser_selector_ambiguous',
62
+ 'browser_session_missing', 'browser_session_limit', 'browser_tab_missing', 'browser_tab_limit',
63
+ 'invalid_browser_tab', 'browser_selector_missing', 'browser_selector_ambiguous',
60
64
  'browser_secret_input_requires_secure_reference', 'browser_full_page_too_large',
61
65
  'browser_element_too_large', 'browser_screenshot_too_large', 'browser_output_outside_workspace',
62
66
  'browser_image_upload_unavailable', 'destructive_command_requires_approval',
@@ -286,6 +290,8 @@ async function api(profile, method, route, body) {
286
290
  if (response.status >= 300 && response.status < 400)
287
291
  throw new Error(`Revo API ${method} ${route} redirected; refusing to forward credentials.`);
288
292
  const value = await response.json().catch(() => ({}));
293
+ if ([401, 403].includes(response.status))
294
+ throw new TerminalRunnerFatalError('Terminal authentication or authorization was rejected. Renew the CLI credentials or grant before connecting.');
289
295
  if (!response.ok)
290
296
  throw new Error(`Revo API ${method} ${route} returned ${response.status}: ${String(value?.message || 'request failed')}`);
291
297
  return (value?.data ?? value);
@@ -416,7 +422,7 @@ export async function runCommand(input, onDone, onChunk) {
416
422
  }, 2_000);
417
423
  hardStop.unref?.();
418
424
  };
419
- const timer = setTimeout(() => { timedOut = true; terminate(); }, Math.min(Math.max(input.timeoutMs, 1_000), MAX_TERMINAL_PROCESS_MS));
425
+ const timer = input.background === true ? undefined : setTimeout(() => { timedOut = true; terminate(); }, Math.min(Math.max(input.timeoutMs, 1_000), MAX_TERMINAL_PROCESS_MS));
420
426
  let policyTimer;
421
427
  const updatePolicyDeadline = (deadline) => {
422
428
  if (policyTimer)
@@ -472,11 +478,12 @@ export async function runCommand(input, onDone, onChunk) {
472
478
  child?.stdout?.on('data', (chunk) => append(chunk, 'stdout'));
473
479
  child?.stderr?.on('data', (chunk) => append(chunk, 'stderr'));
474
480
  terminal?.onData(text => append(Buffer.from(text), 'stdout'));
475
- const finish = (exitCode, error) => {
481
+ const finish = (exitCode, error, signal) => {
476
482
  if (finished)
477
483
  return;
478
484
  finished = true;
479
- clearTimeout(timer);
485
+ if (timer)
486
+ clearTimeout(timer);
480
487
  if (policyTimer)
481
488
  clearTimeout(policyTimer);
482
489
  const diagnostic = [error?.message, policyExpired ? 'terminal_policy_expired' : null].filter(Boolean).join('\n');
@@ -499,9 +506,10 @@ export async function runCommand(input, onDone, onChunk) {
499
506
  onDone({ executed: !error, exitCode: (timedOut || policyExpired) && exitCode === 0 ? null : exitCode,
500
507
  stdout, stderr,
501
508
  timedOut, truncated, logTruncated, logPath: logFd === undefined ? '' : logPath,
509
+ ...(signal ? { signal } : {}),
502
510
  ...(policyExpired ? { policyExpired: true } : {}) });
503
511
  };
504
- child?.on('close', code => finish(code));
512
+ child?.on('close', (code, signal) => finish(code, undefined, signal));
505
513
  child?.on('error', error => finish(null, error));
506
514
  terminal?.onExit(({ exitCode }) => finish(exitCode));
507
515
  return { pid, terminate, updatePolicyDeadline,
@@ -621,7 +629,9 @@ async function connect(profile, device) {
621
629
  let stopped = 0;
622
630
  for (const [executionId, child] of children) {
623
631
  const policy = activePolicies.get(executionId);
624
- if (!policy || !executionAllowedByGrant(policy, grant)) {
632
+ if (!policy || (policy.agentTerminalWorkspaceId
633
+ && policy.policyGrantRevision !== revision) || (policy.commandAccessForThread || policy.networkAccessForThread)
634
+ && policy.policyGrantRevision !== revision || !executionAllowedByGrant(policy, grant)) {
625
635
  cancelledExecutions.add(executionId);
626
636
  child.terminate();
627
637
  stopped++;
@@ -629,7 +639,7 @@ async function connect(profile, device) {
629
639
  else
630
640
  child.updatePolicyDeadline?.(remainingPolicyDeadline(policy, grant));
631
641
  }
632
- const closed = await reconcileBrowserSessions(grant.networkMode);
642
+ const closed = await reconcileBrowserSessions(grant.networkMode, revision);
633
643
  operationalLog.write(stopped || closed ? 'WARN' : 'INFO', {}, 'terminal.policy_updated', { stoppedExecutions: stopped, closedBrowserSessions: closed });
634
644
  };
635
645
  const sendCurrent = (frame) => {
@@ -674,7 +684,7 @@ async function connect(profile, device) {
674
684
  });
675
685
  activeSocket = socket;
676
686
  let connectionId = '';
677
- let workspace = device.workspace;
687
+ let defaultWorkspace = device.workspace;
678
688
  let heartbeat;
679
689
  let lastHeartbeat = Date.now();
680
690
  let incoming = Promise.resolve();
@@ -684,9 +694,10 @@ async function connect(profile, device) {
684
694
  });
685
695
  socket.on('open', () => send(socket, { type: 'hello', protocol: 1, agentTerminalId: device.agentTerminalId,
686
696
  secret: device.secret, capabilities: ['workspace_sandbox_v1', 'workspace_network_v1', 'network_policy_v1',
687
- 'terminal_policy_v2', 'terminal_policy_selective_v1',
697
+ 'terminal_policy_v2', 'terminal_policy_selective_v1', 'background_shell_v1', 'terminal_thread_scope_v1',
688
698
  'apply_patch_v1', 'stdin_v1', 'pty_v1', 'browser_v1', 'browser_session_v1', 'browser_forms_v1',
689
- 'browser_local_v1', 'browser_once_v1', 'browser_secure_input_v1', 'save_image_v1',
699
+ 'browser_local_v1', 'browser_once_v1', 'browser_secure_input_v1', 'browser_tabs_v1', 'save_image_v1',
700
+ 'browser_timeout_v1', 'terminal_workspaces_v1', 'file_transfer_v1', 'browser_control_v1',
690
701
  ...(process.platform === 'darwin' ? ['localhost_shell_v1'] : [])],
691
702
  secureBrowserPublicKey: secureIdentity.publicKey, secureBrowserKeyId: secureIdentity.keyId }));
692
703
  socket.on('message', raw => {
@@ -715,7 +726,7 @@ async function connect(profile, device) {
715
726
  securePolicyEpoch++;
716
727
  connectionId = frame.connectionId;
717
728
  activeConnectionId = connectionId;
718
- workspace = frame.workspace || device.workspace;
729
+ defaultWorkspace = frame.workspace || device.workspace;
719
730
  if (Number.isSafeInteger(frame.policyGrantRevision) && frame.policyGrantRevision >= 0) {
720
731
  minimumPolicyGrantRevision = Math.max(minimumPolicyGrantRevision, frame.policyGrantRevision);
721
732
  policyRevisionUnavailable = false;
@@ -737,12 +748,20 @@ async function connect(profile, device) {
737
748
  socket.terminate();
738
749
  return;
739
750
  }
740
- send(socket, { type: 'heartbeat', connectionId });
751
+ send(socket, { type: 'heartbeat', connectionId, threadBrowserScopes: threadBrowserScopes(), browserSessionIds: browserSessionIds() });
741
752
  }, 15_000);
742
753
  return;
743
754
  }
744
755
  if (frame.type === 'heartbeat')
745
756
  return;
757
+ if (frame.type === 'browser_scope_revoked') {
758
+ if (frame.connectionId === connectionId && typeof frame.browserSessionId === 'string'
759
+ && /^[a-f0-9]{64}$/u.test(frame.browserSessionId)) {
760
+ securePolicyEpoch++;
761
+ await closeThreadBrowserSession(frame.browserSessionId);
762
+ }
763
+ return;
764
+ }
746
765
  if (frame.type === 'policy_updated') {
747
766
  const update = frame;
748
767
  if (update.connectionId !== connectionId)
@@ -799,6 +818,7 @@ async function connect(profile, device) {
799
818
  const envelope = frame;
800
819
  const value = decryptSecureBrowserInput(envelope, secureIdentity);
801
820
  await fillBrowserSecret({ browserSessionId: envelope.browserSessionId,
821
+ browserTabId: envelope.browserTabId,
802
822
  origin: envelope.origin, selector: envelope.selector,
803
823
  expiresAt: envelope.expiresAt, value,
804
824
  isAuthorized: () => requestEpoch === securePolicyEpoch && !stopping
@@ -842,7 +862,9 @@ async function connect(profile, device) {
842
862
  if (frame.type === 'cancel') {
843
863
  const child = children.get(frame.executionId);
844
864
  if (child) {
845
- operationalLog.write('WARN', traces.get(frame.executionId) || { executionId: frame.executionId }, 'execution.cancel_requested');
865
+ operationalLog.write('WARN', traces.get(frame.executionId) || { executionId: frame.executionId }, 'execution.cancel_requested', { reason: ['background_execution_invalid', 'background_dispatch_invalid',
866
+ 'background_binding_invalid', 'background_authorization_invalid'].includes(frame.cancelCause || '')
867
+ ? frame.cancelCause : 'cancel_requested' });
846
868
  cancelledExecutions.add(frame.executionId);
847
869
  child.terminate();
848
870
  }
@@ -880,6 +902,12 @@ async function connect(profile, device) {
880
902
  send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
881
903
  return;
882
904
  }
905
+ const workspace = frame.agentTerminalWorkspaceId ? frame.workspace : defaultWorkspace;
906
+ if (typeof workspace !== 'string' || !path.isAbsolute(workspace)) {
907
+ sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
908
+ executed: false, exitCode: null, stdout: '', stderr: 'workspace_unavailable', timedOut: false });
909
+ return;
910
+ }
883
911
  const operation = frame.operation || 'shell';
884
912
  const trace = { assistantThreadId: frame.assistantThreadId,
885
913
  assistantMessageId: frame.assistantMessageId, executionId: frame.executionId };
@@ -888,10 +916,11 @@ async function connect(profile, device) {
888
916
  && typeof frame.browserSessionId === 'string' && frame.browserAction) {
889
917
  try {
890
918
  validateBrowserActionInput({ url: frame.url, action: frame.browserAction,
891
- workspace, browserSessionId: frame.browserSessionId, selector: frame.selector,
919
+ workspace, browserSessionId: frame.browserSessionId, tabId: frame.tabId, selector: frame.selector,
892
920
  width: frame.width, height: frame.height, value: frame.value, checked: frame.checked,
893
921
  key: frame.key, deltaY: frame.deltaY, state: frame.state,
894
922
  waitTimeoutMs: frame.waitTimeoutMs, capture: frame.capture, clip: frame.clip,
923
+ actionTimeoutMs: frame.actionTimeoutMs,
895
924
  localOnly: frame.browserLocalOnly === true });
896
925
  validBrowserPayload = true;
897
926
  }
@@ -900,11 +929,15 @@ async function connect(profile, device) {
900
929
  const validPayload = operation === 'apply_patch'
901
930
  ? typeof frame.patch === 'string' && Buffer.byteLength(frame.patch) <= 64_000
902
931
  : operation === 'browser' ? validBrowserPayload
903
- : operation === 'save_image' ? Array.isArray(frame.files) && frame.files.length > 0 && frame.files.length <= 32
904
- : operation === 'shell' && typeof frame.cmd === 'string' && !!frame.cmd.trim() && frame.cmd.length <= 8_192;
905
- if (!validPayload || children.size >= 4 || !isTerminalSandbox(frame.sandbox)
932
+ : operation === 'upload_file' || operation === 'download_file' ? validateFileTransfer(frame.transfer)
933
+ : operation === 'save_image' ? Array.isArray(frame.files) && frame.files.length > 0 && frame.files.length <= 32
934
+ : operation === 'shell' && typeof frame.cmd === 'string' && !!frame.cmd.trim() && frame.cmd.length <= 8_192;
935
+ if (!validPayload || operation !== 'browser' && frame.actionTimeoutMs != null
936
+ || frame.background !== undefined && typeof frame.background !== 'boolean'
937
+ || frame.background === true && (operation !== 'shell' || frame.timeoutMs != null)
938
+ || children.size >= 4 || !isTerminalSandbox(frame.sandbox)
906
939
  || operation === 'apply_patch' && frame.sandbox === 'workspace-network'
907
- || (operation === 'browser' || operation === 'save_image') && frame.sandbox !== 'workspace-network'
940
+ || (operation === 'browser' || operation === 'save_image' || operation === 'upload_file' || operation === 'download_file') && frame.sandbox !== 'workspace-network'
908
941
  || frame.tty === true && (operation !== 'shell' || !Number.isInteger(frame.cols) || !Number.isInteger(frame.rows)
909
942
  || frame.cols < 20 || frame.cols > 240 || frame.rows < 10 || frame.rows > 100)) {
910
943
  operationalLog.write('WARN', trace, 'execution.rejected', { operation,
@@ -926,7 +959,7 @@ async function connect(profile, device) {
926
959
  operationalLog.write('INFO', trace, 'execution.started', { operation, sandbox: frame.sandbox });
927
960
  resumed.add(frame.executionId);
928
961
  outputByExecution.set(frame.executionId, []);
929
- if (operation === 'save_image') {
962
+ if (operation === 'save_image' || operation === 'upload_file' || operation === 'download_file') {
930
963
  const controller = new AbortController();
931
964
  const policyDeadline = executionPolicyDeadline(frame);
932
965
  let policyTimer;
@@ -944,14 +977,16 @@ async function connect(profile, device) {
944
977
  children.set(frame.executionId, child);
945
978
  activeChildren.add(child);
946
979
  send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
947
- void uploadWorkspaceImages(workspace, frame.files, controller.signal).then(count => {
980
+ const transfer = operation === 'save_image' ? uploadWorkspaceImages(workspace, frame.files, controller.signal)
981
+ : transferWorkspaceFile(workspace, operation, frame.transfer, controller.signal);
982
+ void transfer.then(count => {
948
983
  if (policyTimer)
949
984
  clearTimeout(policyTimer);
950
985
  children.delete(frame.executionId);
951
986
  activePolicies.delete(frame.executionId);
952
987
  activeChildren.delete(child);
953
- completed.set(frame.executionId, { executed: true, exitCode: 0, stdout: `Uploaded ${count} image(s).`, stderr: '' });
954
- operationalLog.write('INFO', trace, 'execution.completed', { operation, exitCode: 0, images: count });
988
+ completed.set(frame.executionId, { executed: true, exitCode: 0, stdout: operation === 'save_image' ? `Uploaded ${count} image(s).` : JSON.stringify(count), stderr: '' });
989
+ operationalLog.write('INFO', trace, 'execution.completed', { operation, exitCode: 0, images: operation === 'save_image' ? count : undefined });
955
990
  if (resumed.has(frame.executionId))
956
991
  flushExecution(frame.executionId);
957
992
  }).catch(error => {
@@ -960,8 +995,9 @@ async function connect(profile, device) {
960
995
  children.delete(frame.executionId);
961
996
  activePolicies.delete(frame.executionId);
962
997
  activeChildren.delete(child);
963
- completed.set(frame.executionId, { executed: false, exitCode: null, stdout: '',
964
- stderr: error instanceof Error ? error.message : 'image_upload_failed' });
998
+ completed.set(frame.executionId, { executed: operation === 'upload_file' && error instanceof Error
999
+ && ['file_transfer_transport_failed', 'file_transfer_source_changed'].includes(error.message), exitCode: null, stdout: '',
1000
+ stderr: error instanceof Error && /^[a-z][a-z_0-9]+$/u.test(error.message) ? error.message : 'file_transfer_failed' });
965
1001
  operationalLog.write('ERROR', trace, 'execution.failed', { operation,
966
1002
  errorCode: 'image_upload_failed' });
967
1003
  if (resumed.has(frame.executionId))
@@ -988,15 +1024,19 @@ async function connect(profile, device) {
988
1024
  children.set(frame.executionId, child);
989
1025
  activeChildren.add(child);
990
1026
  send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
991
- void runBrowserAction({ url: frame.url, action: frame.browserAction, workspace,
992
- browserSessionId: frame.browserSessionId, onActionAttempt: () => { actionAttempted = true; },
1027
+ void runBrowserAction({ url: frame.url, action: frame.browserAction, workspace, agentTerminalWorkspaceId: frame.agentTerminalWorkspaceId,
1028
+ browserSessionId: frame.browserSessionId, tabId: frame.tabId,
1029
+ onActionAttempt: () => { actionAttempted = true; },
993
1030
  selector: frame.selector, width: frame.width, height: frame.height,
994
1031
  value: frame.value, checked: frame.checked, key: frame.key, deltaY: frame.deltaY,
995
1032
  state: frame.state, waitTimeoutMs: frame.waitTimeoutMs,
1033
+ actionTimeoutMs: frame.actionTimeoutMs,
996
1034
  capture: frame.capture, clip: frame.clip,
997
1035
  localOnly: frame.browserLocalOnly === true,
998
1036
  networkAccessExpiresAt: frame.networkAccessExpiresAt,
999
1037
  networkAccessOnce: frame.networkAccessOnce,
1038
+ networkAccessForThread: frame.networkAccessForThread, actorUserId: frame.actorUserId,
1039
+ threadId: frame.browserTargetThreadId || frame.assistantThreadId, policyGrantRevision: frame.policyGrantRevision,
1000
1040
  signal: controller.signal })
1001
1041
  .then(async (browserResult) => {
1002
1042
  if (frame.browserAction === 'screenshot') {
@@ -1012,6 +1052,8 @@ async function connect(profile, device) {
1012
1052
  completed.set(frame.executionId, { executed: true, exitCode: 0,
1013
1053
  stdout: browserResult.dom, stderr: '', screenshotPath: browserResult.screenshotPath || null,
1014
1054
  pageUrl: browserResult.pageUrl,
1055
+ browserSessionId: browserResult.browserSessionId, activeTabId: browserResult.activeTabId,
1056
+ tabs: browserResult.tabs, sessionCreated: browserResult.sessionCreated,
1015
1057
  cancelled: cancelledExecutions.delete(frame.executionId) });
1016
1058
  operationalLog.write('INFO', trace, 'execution.completed', { operation,
1017
1059
  browserAction: frame.browserAction, exitCode: 0, screenshot: frame.browserAction === 'screenshot' });
@@ -1068,7 +1110,7 @@ async function connect(profile, device) {
1068
1110
  const child = await runCommand({ cmd: frame.cmd, workdir: frame.workdir || workspace,
1069
1111
  workspace, sandbox: frame.sandbox, networkAccess: frame.networkAccess,
1070
1112
  policyDeadlineMs: executionPolicyDeadline(frame),
1071
- timeoutMs: frame.timeoutMs || 60_000, tty: frame.tty,
1113
+ timeoutMs: frame.timeoutMs || 60_000, background: frame.background === true, tty: frame.tty,
1072
1114
  cols: frame.cols, rows: frame.rows,
1073
1115
  executionId: frame.executionId }, result => {
1074
1116
  children.delete(frame.executionId);
@@ -1077,7 +1119,8 @@ async function connect(profile, device) {
1077
1119
  const { stdout, stderr, ...completion } = result;
1078
1120
  completed.set(frame.executionId, { ...completion,
1079
1121
  cancelled: cancelledExecutions.delete(frame.executionId), stdout: '', stderr: '' });
1080
- operationalLog.write(completion.exitCode === 0 ? 'INFO' : 'ERROR', trace, completion.exitCode === 0 ? 'execution.completed' : 'execution.failed', { operation, exitCode: completion.exitCode ?? 'none', executed: completion.executed,
1122
+ operationalLog.write(completion.exitCode === 0 ? 'INFO' : 'ERROR', trace, completion.exitCode === 0 ? 'execution.completed' : 'execution.failed', { operation, exitCode: completion.exitCode ?? 'none', signal: completion.signal,
1123
+ executed: completion.executed,
1081
1124
  timedOut: completion.timedOut, truncated: completion.truncated });
1082
1125
  if (resumed.has(frame.executionId))
1083
1126
  sendCurrent({ type: 'result', executionId: frame.executionId,
@@ -1126,18 +1169,30 @@ async function connect(profile, device) {
1126
1169
  if (activeSocket === socket)
1127
1170
  activeSocket = undefined;
1128
1171
  if (code === 1008 && reason.toString() !== 'heartbeat_timeout')
1129
- reject(new Error(`Runner rejected by Realtime: ${reason.toString() || 'policy violation'}.`));
1172
+ reject(new TerminalRunnerFatalError(`Runner rejected by Realtime: ${reason.toString() || 'policy violation'}.`));
1130
1173
  else
1131
1174
  resolve();
1132
1175
  });
1176
+ socket.on('unexpected-response', (_request, response) => {
1177
+ response.resume();
1178
+ if ([401, 403].includes(response.statusCode || 0)) {
1179
+ stopping = true;
1180
+ socket.terminate();
1181
+ reject(new TerminalRunnerFatalError('Runner authentication was rejected. Renew the CLI credentials before connecting.'));
1182
+ }
1183
+ else
1184
+ socket.terminate();
1185
+ });
1133
1186
  socket.on('error', () => {
1187
+ if (stopping)
1188
+ return;
1134
1189
  operationalLog.write('WARN', {}, 'socket.error');
1135
1190
  console.error('Realtime connection failed; terminal will retry.');
1136
1191
  });
1137
1192
  });
1138
1193
  }
1139
1194
  catch (error) {
1140
- if (error instanceof Error && error.message.startsWith('Runner rejected by Realtime:'))
1195
+ if (error instanceof TerminalRunnerFatalError)
1141
1196
  throw error;
1142
1197
  operationalLog.write('WARN', {}, 'runner.connect_failed', { errorCode: operationalErrorCode(error) });
1143
1198
  console.error('Terminal connection failed; retrying.');
@@ -1155,7 +1210,7 @@ async function connect(profile, device) {
1155
1210
  process.off('SIGTERM', stop);
1156
1211
  }
1157
1212
  }
1158
- export async function handleTerminalCommand(argv) {
1213
+ async function runTerminalCommand(argv) {
1159
1214
  const command = argv[0] || 'help';
1160
1215
  if (command === 'help' || argv.includes('--help')) {
1161
1216
  console.log('revo terminal connect|status|disconnect [--project NAME] [--workspace PATH] [--name NAME|--terminal-id UUID] [--url URL] [--realtime-url URL]\nrevo terminal service install|uninstall --workspace PATH [--project NAME] [--name NAME|--terminal-id UUID]');
@@ -1177,7 +1232,7 @@ export async function handleTerminalCommand(argv) {
1177
1232
  const { name, terminalId } = terminalSelector(argv);
1178
1233
  const saved = envName === 'default' ? loadStoredConfig({ allowLegacy: false }) : getEnvironmentProfile(envName);
1179
1234
  const baseUrl = saved?.baseUrl?.replace(/\/$/, '');
1180
- const devices = readStore().devices.filter(item => item.workspace === workspace && item.baseUrl === baseUrl
1235
+ const devices = readStore().devices.filter(item => (item.workspace === workspace || item.workspaces?.includes(workspace)) && item.baseUrl === baseUrl
1181
1236
  && (!saved?.instance || item.instance === saved.instance));
1182
1237
  const matching = devices.filter(item => terminalId ? item.agentTerminalId === terminalId : item.name === name);
1183
1238
  if (action === 'uninstall') {
@@ -1186,9 +1241,9 @@ export async function handleTerminalCommand(argv) {
1186
1241
  if (!terminalId && matching.length === 0 && option(argv, 'name'))
1187
1242
  throw new Error('No local terminal registration matches --name. Use --terminal-id to uninstall its service.');
1188
1243
  const selectedId = terminalId || matching[0]?.agentTerminalId;
1189
- const result = uninstallTerminalService({ workspace, envName,
1244
+ const result = uninstallTerminalService({ workspace: matching[0]?.workspace || workspace, envName,
1190
1245
  terminalId: selectedId && (terminalId || option(argv, 'name')
1191
- || terminalServiceInstalled(workspace, envName, selectedId)) ? selectedId : undefined,
1246
+ || terminalServiceInstalled(matching[0]?.workspace || workspace, envName, selectedId)) ? selectedId : undefined,
1192
1247
  configHome: process.env.XDG_CONFIG_HOME });
1193
1248
  console.log(result.removed ? `Terminal service stopped and removed (${result.label}). Grant remains active.`
1194
1249
  : `No terminal service installed for this workspace (${result.label}).`);
@@ -1210,9 +1265,10 @@ export async function handleTerminalCommand(argv) {
1210
1265
  const selected = selectRegisteredTerminal(matching, listing.devices, name, terminalId);
1211
1266
  if (!selected || !listing.devices.some(grant => grant.agentTerminalId === selected.agentTerminalId && grant.status === 'approved'))
1212
1267
  throw new Error('The selected terminal is not approved.');
1213
- if (terminalServiceInstalled(workspace, envName))
1268
+ const serviceWorkspace = selected.workspace;
1269
+ if (terminalServiceInstalled(serviceWorkspace, envName))
1214
1270
  throw new Error('Uninstall the legacy workspace service before installing a terminal-specific service.');
1215
- if (!terminalServiceInstalled(workspace, envName, selected.agentTerminalId)) {
1271
+ if (!terminalServiceInstalled(serviceWorkspace, envName, selected.agentTerminalId)) {
1216
1272
  let releaseRunnerLock;
1217
1273
  try {
1218
1274
  releaseRunnerLock = acquireRunnerLock(selected.agentTerminalId);
@@ -1224,7 +1280,7 @@ export async function handleTerminalCommand(argv) {
1224
1280
  }
1225
1281
  releaseRunnerLock();
1226
1282
  }
1227
- const result = installTerminalService({ workspace, envName, terminalId: selected.agentTerminalId,
1283
+ const result = installTerminalService({ workspace: serviceWorkspace, envName, terminalId: selected.agentTerminalId,
1228
1284
  pathValue: process.env.PATH,
1229
1285
  configHome: process.env.XDG_CONFIG_HOME });
1230
1286
  console.log(result.installed ? `Terminal service installed and started (${result.label}).`
@@ -1245,7 +1301,7 @@ export async function handleTerminalCommand(argv) {
1245
1301
  const selector = terminalSelector(argv);
1246
1302
  let { name } = selector;
1247
1303
  const { terminalId } = selector;
1248
- const profileDevices = store.devices.filter(item => item.workspace === workspace
1304
+ const profileDevices = store.devices.filter(item => (command === 'connect' || item.workspace === workspace || item.workspaces?.includes(workspace))
1249
1305
  && item.baseUrl === profile.baseUrl && item.instance === profile.instance);
1250
1306
  let matchingDevices = profileDevices.filter(item => terminalId ? item.agentTerminalId === terminalId : item.name === name);
1251
1307
  if (command === 'connect' && !terminalId && option(argv, 'name') === undefined
@@ -1270,8 +1326,8 @@ export async function handleTerminalCommand(argv) {
1270
1326
  throw new Error(`Multiple removed terminals match ${name} (${matchingDevices.map(item => item.agentTerminalId).join(', ')}). Select one with --terminal-id.`);
1271
1327
  selectedDevice = matchingDevices[0];
1272
1328
  }
1273
- if (terminalServiceInstalled(workspace, selectedProject(argv) || getActiveEnvironmentName(), selectedDevice.agentTerminalId)
1274
- || terminalServiceInstalled(workspace, selectedProject(argv) || getActiveEnvironmentName()))
1329
+ if (terminalServiceInstalled(selectedDevice.workspace, selectedProject(argv) || getActiveEnvironmentName(), selectedDevice.agentTerminalId)
1330
+ || terminalServiceInstalled(selectedDevice.workspace, selectedProject(argv) || getActiveEnvironmentName()))
1275
1331
  throw new Error('Uninstall the selected terminal service before revoking its grant.');
1276
1332
  if (listing.devices.some(item => item.agentTerminalId === selectedDevice.agentTerminalId))
1277
1333
  await api(profile, 'POST', `/agents/terminals/${selectedDevice.agentTerminalId}/revoke`);
@@ -1284,7 +1340,8 @@ export async function handleTerminalCommand(argv) {
1284
1340
  if (command === 'status') {
1285
1341
  const listing = await api(profile, 'GET', '/agents/terminals');
1286
1342
  console.log(JSON.stringify({ devices: listing.devices.map(item => ({ agentTerminalId: item.agentTerminalId, name: item.name, workspace: item.workspace,
1287
- status: item.status, mode: item.mode, networkMode: item.networkMode })) }, null, 2));
1343
+ workspaces: item.workspaces, status: item.status, mode: item.mode, networkMode: item.networkMode,
1344
+ revision: item.revision, connectionRevision: item.connectionRevision, online: item.online, lastOnlineAt: item.lastOnlineAt })) }, null, 2));
1288
1345
  return;
1289
1346
  }
1290
1347
  if (command !== 'connect')
@@ -1304,7 +1361,7 @@ export async function handleTerminalCommand(argv) {
1304
1361
  }
1305
1362
  }
1306
1363
  if (terminalId && !device)
1307
- throw new Error('No approved or pending local terminal registration matches --terminal-id.');
1364
+ throw new TerminalRunnerFatalError('No approved or pending local terminal registration matches --terminal-id.');
1308
1365
  if (!device) {
1309
1366
  const currentUser = me || await api(profile, 'GET', '/me');
1310
1367
  const rt = option(argv, 'realtime-url') || profile.realtimeUrl || currentUser.instance?.endpoints?.realtime;
@@ -1334,16 +1391,35 @@ export async function handleTerminalCommand(argv) {
1334
1391
  }
1335
1392
  console.log(`Pending approval in AI Agents → Terminals: ${device.name} (${device.agentTerminalId}).`);
1336
1393
  }
1394
+ if (device.workspace !== workspace) {
1395
+ await api(profile, 'POST', `/agents/terminals/${device.agentTerminalId}/workspaces/register`, { path: workspace, name: path.basename(workspace) });
1396
+ await updateStore(current => {
1397
+ const saved = current.devices.find(item => item.agentTerminalId === device.agentTerminalId);
1398
+ if (saved)
1399
+ saved.workspaces = [...new Set([...(saved.workspaces || [saved.workspace]), workspace])];
1400
+ });
1401
+ console.log(`Workspace registered on ${device.name} (${device.agentTerminalId}). Approve its access in AI Agents → Terminals.`);
1402
+ }
1337
1403
  for (;;) {
1338
1404
  const listing = await api(profile, 'GET', '/agents/terminals');
1339
1405
  const grant = listing.devices.find(item => item.agentTerminalId === device.agentTerminalId);
1340
1406
  if (grant?.status === 'approved')
1341
1407
  break;
1342
1408
  if (!grant || grant.status === 'revoked')
1343
- throw new Error('Terminal grant revoked or missing.');
1409
+ throw new TerminalRunnerFatalError('Terminal grant revoked or missing.');
1344
1410
  await new Promise(resolve => setTimeout(resolve, 2_000));
1345
1411
  }
1346
- const releaseRunnerLock = acquireRunnerLock(device.agentTerminalId);
1412
+ let releaseRunnerLock;
1413
+ try {
1414
+ releaseRunnerLock = acquireRunnerLock(device.agentTerminalId);
1415
+ }
1416
+ catch (error) {
1417
+ if (error instanceof Error && error.message.includes('already connected')) {
1418
+ console.log(`Terminal ${device.agentTerminalId} already has a local runner; its workspace contract will refresh automatically.`);
1419
+ return;
1420
+ }
1421
+ throw error;
1422
+ }
1347
1423
  try {
1348
1424
  await connect(profile, device);
1349
1425
  }
@@ -1351,3 +1427,16 @@ export async function handleTerminalCommand(argv) {
1351
1427
  releaseRunnerLock();
1352
1428
  }
1353
1429
  }
1430
+ /** Supervisors retry crashes, but a revoked grant or 401/403 needs a human credential/grant change. */
1431
+ export async function handleTerminalCommand(argv) {
1432
+ try {
1433
+ await runTerminalCommand(argv);
1434
+ }
1435
+ catch (error) {
1436
+ if (argv.includes('--service-runner') && error instanceof TerminalRunnerFatalError) {
1437
+ console.error(error.message);
1438
+ return;
1439
+ }
1440
+ throw error;
1441
+ }
1442
+ }
@@ -44,6 +44,9 @@ export type GroupLockEntry = {
44
44
  export type GroupOwnerPolicy = {
45
45
  type: 'group';
46
46
  stableKey: string;
47
+ } | {
48
+ type: 'service-account';
49
+ stableKey: string;
47
50
  } | {
48
51
  type: 'manual-user';
49
52
  } | {
@@ -112,6 +115,7 @@ export type RevoLockFile = {
112
115
  components: Record<string, ComponentLockEntry>;
113
116
  groups: Record<string, GroupLockEntry>;
114
117
  roleGroups: Record<string, RoleGroupLockEntry>;
118
+ serviceAccounts: Record<string, RoleGroupLockEntry>;
115
119
  jobTemplates: Record<string, JobTemplateLockEntry>;
116
120
  schedules: Record<string, ScheduleLockEntry>;
117
121
  events: Record<string, EventLockEntry>;