@revoengine/cli 1.0.22 → 1.0.23

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.
package/README.md CHANGED
@@ -82,6 +82,8 @@ revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
82
82
  revo terminal status
83
83
  ```
84
84
 
85
+ For an existing registration, `connect --terminal-id <uuid> --realtime-url <url>` overrides its Realtime endpoint for that invocation without pairing again or changing the saved registration. The URL is normalized to the runner WebSocket route; remote endpoints require TLS.
86
+
85
87
  An approved terminal can run as a per-user background service on macOS or Linux. The service uses the active project at installation, or an explicit `--project <name>`; use the same project when uninstalling after a switch.
86
88
 
87
89
  ```bash
@@ -90,7 +92,9 @@ revo terminal service uninstall --workspace "$HOME/projects/my-project" --name "
90
92
  revo terminal disconnect --workspace "$HOME/projects/my-project" --name "Work Mac"
91
93
  ```
92
94
 
93
- Stop the foreground runner before installing its service. The service starts at login, reconnects automatically, and pins the selected terminal UUID and project profile at installation. Multiple terminals can share one machine and workspace when they have distinct names; pass the same `--name` to `connect`, `service install|uninstall`, and `disconnect`. Without `--name`, the CLI uses the machine hostname. If two registrations have the same name, the CLI refuses an ambiguous choice; use `revo terminal status` to find the UUID and pass `--terminal-id <uuid>`. A legacy workspace service must be uninstalled before installing a terminal-specific service. Uninstall stops the selected service but keeps its grant and local registration. `disconnect` revokes only the selected grant and removes its local credential; uninstall its service first. On macOS, service logs are in `~/Library/Logs/RevoEngine/`. On Linux, inspect them with `journalctl --user -u <unit-name>`; `install` prints the unit name. Linux user services normally stop after logout unless an administrator enables user lingering.
95
+ Stop the foreground runner before installing its service. The service starts at login, reconnects automatically, and pins the selected terminal UUID and project profile at installation. Multiple terminals can share one machine and workspace when they have distinct names; pass the same `--name` to `connect`, `service install|uninstall`, and `disconnect`. Without `--name`, the CLI uses the machine hostname. If two registrations have the same name, the CLI refuses an ambiguous choice; use `revo terminal status` to find the UUID and pass `--terminal-id <uuid>`. A legacy workspace service must be uninstalled before installing a terminal-specific service. Uninstall stops the selected service but keeps its grant and local registration. `disconnect` stops/removes the selected terminal-specific service, revokes its grant and removes its local credential. Uninstall a legacy workspace service first so it cannot affect a different terminal. On macOS, service logs are in `~/Library/Logs/RevoEngine/`. On Linux, inspect them with `journalctl --user -u <unit-name>`; `install` prints the unit name. Linux user services normally stop after logout unless an administrator enables user lingering.
96
+
97
+ The runner retries temporary API startup failures and WebSocket outages without a retry-count limit, using exponential backoff capped at 30 seconds with jitter. Startup reads have a 30-second request deadline; pairing and other writes are not automatically repeated. Ctrl+C or SIGTERM interrupts both a pending API request and a reconnect wait. Realtime restarts and Cloud Run connection timeouts renew transport without revoking the device. A newly supported ACL-change renewal immediately stops work under the old connection and reconnects against the current approved grant; it never extends the old command permission. Older runners stop on that change and need restarting. Actual grant/account/API-key revocation, expiration or invalid frames stop the runner; background services do not restart these deliberate security cutoffs. Availability has no fixed 30-day runner expiry, but depends on the machine, network, valid credentials and supervisor remaining available. An outage longer than the three-minute recovery window stops existing processes and Browser sessions; the runner continues reconnecting afterward.
94
98
 
95
99
  Runner credentials are stored in `runner.json` beside the CLI configuration. Each executed shell command writes raw output to a private `runner-logs/<executionId>.log` there, capped at 10 MB per file. Logs older than 24 hours are removed when the next command starts; a runner left idle does not perform timed cleanup. Optional CLI HTTP tracing writes sanitized request metadata under the project `.revoengine/logs/http-trace/`. These are separate from the Assistant's server-side tool history and do not form a complete local transcript. Treat runner logs as sensitive because command output may contain secrets.
96
100
 
@@ -458,6 +462,8 @@ revo database-tables push 'Sales/Orders#1234abcd' --project target --yes
458
462
  revo database-views push 'Sales/Revenue#1234abcd' --project target --yes
459
463
  ```
460
464
 
465
+ Endpoint route uniqueness applies to live resources, matching the API. Soft-deleted endpoints with other Stable Keys do not reserve routes. Exact-key restore also checks the endpoint's old route during planning and again immediately before restoration, even when the desired path changes. The backend remains the final authority for concurrent route changes.
466
+
461
467
  Database View plans show a line diff for changed RAW_SQL queries, including unchanged context and red/green removed and added lines in color terminals.
462
468
 
463
469
  Preview failures use `validation-failed`, preserve the definition diff, and show the backend message, HTTP status, definition mode, and timeout information. RAW_SQL failures also suggest checking whether the instance enables RAW SQL Database Views. They block deployment of the affected view even with `--force`; `database-views push` continues with independent views but exits unsuccessfully if validation failed. An unchanged view skips planning preview only when its target hash and source-table dependency fingerprint match the environment lock; old locks still require preview. Pull and verified push update this fingerprint, while plan remains fileless. Creates and updates always revalidate immediately before writing.
@@ -1,5 +1,7 @@
1
1
  import { type ChildProcess } from 'node:child_process';
2
2
  import { type TerminalNetworkAccess, type TerminalSandbox } from './terminal-sandbox.ts';
3
+ /** Equal jitter avoids synchronized reconnect storms while retaining a bounded delay. */
4
+ export declare function terminalReconnectDelay(backoffMs: number, random?: number): number;
3
5
  type TerminalGrant = {
4
6
  agentTerminalId: string;
5
7
  name?: string;
@@ -1,4 +1,5 @@
1
1
  import fs from 'node:fs';
2
+ import { setTimeout as delay } from 'node:timers/promises';
2
3
  import os from 'node:os';
3
4
  import path from 'node:path';
4
5
  import { fileURLToPath } from 'node:url';
@@ -18,6 +19,12 @@ import { TerminalOperationalLog } from "./terminal-operational-log.js";
18
19
  import { createSecureBrowserIdentity, decryptSecureBrowserInput } from "./terminal-secure-browser.js";
19
20
  class TerminalRunnerFatalError extends Error {
20
21
  }
22
+ class TerminalApiTransientError extends Error {
23
+ }
24
+ /** Equal jitter avoids synchronized reconnect storms while retaining a bounded delay. */
25
+ export function terminalReconnectDelay(backoffMs, random = Math.random()) {
26
+ return Math.round(backoffMs * (0.5 + random * 0.5));
27
+ }
21
28
  export function selectRegisteredTerminal(devices, grants, name, terminalId) {
22
29
  const matching = devices.filter(device => terminalId
23
30
  ? device.agentTerminalId === terminalId : device.name === name);
@@ -279,22 +286,60 @@ function apiUrl(profile, route) {
279
286
  return `${base}/api/v1${route}`;
280
287
  }
281
288
  async function api(profile, method, route, body) {
282
- const response = await fetch(apiUrl(profile, route), {
283
- method,
284
- redirect: 'manual',
285
- headers: { Authorization: `Bearer ${profile.token}`,
286
- ...(profile.instance ? { instance: profile.instance } : {}),
287
- ...(body ? { 'Content-Type': 'application/json' } : {}) },
288
- ...(body ? { body: JSON.stringify(body) } : {}),
289
- });
290
- if (response.status >= 300 && response.status < 400)
291
- throw new Error(`Revo API ${method} ${route} redirected; refusing to forward credentials.`);
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.');
295
- if (!response.ok)
296
- throw new Error(`Revo API ${method} ${route} returned ${response.status}: ${String(value?.message || 'request failed')}`);
297
- return (value?.data ?? value);
289
+ const url = apiUrl(profile, route);
290
+ let backoffMs = 1_000;
291
+ for (;;) {
292
+ profile.signal?.throwIfAborted();
293
+ try {
294
+ let response;
295
+ try {
296
+ response = await fetch(url, {
297
+ method, redirect: 'manual',
298
+ signal: AbortSignal.any([AbortSignal.timeout(30_000), ...(profile.signal ? [profile.signal] : [])]),
299
+ headers: { Authorization: `Bearer ${profile.token}`,
300
+ ...(profile.instance ? { instance: profile.instance } : {}),
301
+ ...(body ? { 'Content-Type': 'application/json' } : {}) },
302
+ ...(body ? { body: JSON.stringify(body) } : {}),
303
+ });
304
+ }
305
+ catch {
306
+ throw new TerminalApiTransientError('Terminal API transport unavailable.');
307
+ }
308
+ if (response.status >= 300 && response.status < 400) {
309
+ await response.body?.cancel();
310
+ throw new Error(`Revo API ${method} ${route} redirected; refusing to forward credentials.`);
311
+ }
312
+ if ([401, 403].includes(response.status)) {
313
+ await response.body?.cancel();
314
+ throw new TerminalRunnerFatalError('Terminal authentication or authorization was rejected. Renew the CLI credentials or grant before connecting.');
315
+ }
316
+ if ([408, 429].includes(response.status) || response.status >= 500) {
317
+ await response.body?.cancel();
318
+ throw new TerminalApiTransientError(`Terminal API temporarily unavailable (${response.status}).`);
319
+ }
320
+ let value;
321
+ try {
322
+ value = await response.json();
323
+ }
324
+ catch {
325
+ if (!response.ok)
326
+ throw new Error(`Revo API ${method} ${route} returned ${response.status}.`);
327
+ throw new TerminalApiTransientError('Terminal API returned an incomplete response.');
328
+ }
329
+ if (!response.ok)
330
+ throw new Error(`Revo API ${method} ${route} returned ${response.status}: ${String(value?.message || 'request failed')}`);
331
+ return (value?.data ?? value);
332
+ }
333
+ catch (error) {
334
+ profile.signal?.throwIfAborted();
335
+ // Only connect's reads are repeatable. Never replay pairing, revocation or other mutations.
336
+ if (!profile.retryReads || method !== 'GET' || !(error instanceof TerminalApiTransientError))
337
+ throw error;
338
+ console.error('Terminal API unavailable; connection setup will retry.');
339
+ await delay(terminalReconnectDelay(backoffMs), undefined, { signal: profile.signal });
340
+ backoffMs = Math.min(backoffMs * 2, 30_000);
341
+ }
342
+ }
298
343
  }
299
344
  function realtimeUrl(value) {
300
345
  const url = new URL(value);
@@ -533,11 +578,18 @@ export function runWorkspacePatch(input, onDone) {
533
578
  throw new Error('terminal_policy_expired');
534
579
  const workerJs = fileURLToPath(new URL('./terminal-patch-worker.js', import.meta.url));
535
580
  const worker = fs.existsSync(workerJs) ? workerJs : fileURLToPath(new URL('./terminal-patch-worker.ts', import.meta.url));
536
- const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'revo-terminal-patch-'));
581
+ const scratch = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'revo-terminal-patch-')));
537
582
  let launch;
538
583
  try {
539
- const command = [process.execPath, worker, input.workspace, String(input.allowDelete)].map(shellQuote).join(' ');
540
- launch = sandboxCommand(input.workspace, input.workspace, command, 'workspace', process.platform, scratch, [path.dirname(worker)], 'none');
584
+ // Run the fixed helper files from their own package scope. Node's loader must
585
+ // not traverse a CLI installation outside this command's readable workspace.
586
+ const isolatedWorker = path.join(scratch, path.basename(worker));
587
+ const helperName = `terminal-patch${path.extname(worker)}`;
588
+ fs.copyFileSync(worker, isolatedWorker);
589
+ fs.copyFileSync(path.join(path.dirname(worker), helperName), path.join(scratch, helperName));
590
+ fs.writeFileSync(path.join(scratch, 'package.json'), JSON.stringify({ type: 'module' }), { mode: 0o600 });
591
+ const command = [process.execPath, isolatedWorker, input.workspace, String(input.allowDelete)].map(shellQuote).join(' ');
592
+ launch = sandboxCommand(input.workspace, input.workspace, command, 'workspace', process.platform, scratch, [], 'none');
541
593
  }
542
594
  catch (error) {
543
595
  fs.rmSync(scratch, { recursive: true, force: true });
@@ -693,7 +745,7 @@ async function connect(profile, device) {
693
745
  reconnectGrace.clear();
694
746
  });
695
747
  socket.on('open', () => send(socket, { type: 'hello', protocol: 1, agentTerminalId: device.agentTerminalId,
696
- secret: device.secret, capabilities: ['workspace_sandbox_v1', 'workspace_network_v1', 'network_policy_v1',
748
+ secret: device.secret, capabilities: ['grant_refresh_v1', 'workspace_sandbox_v1', 'workspace_network_v1', 'network_policy_v1',
697
749
  'terminal_policy_v2', 'terminal_policy_selective_v1', 'background_shell_v1', 'terminal_thread_scope_v1',
698
750
  'apply_patch_v1', 'stdin_v1', 'pty_v1', 'browser_v1', 'browser_session_v1', 'browser_forms_v1',
699
751
  'browser_local_v1', 'browser_once_v1', 'browser_secure_input_v1', 'browser_tabs_v1', 'save_image_v1',
@@ -1158,10 +1210,13 @@ async function connect(profile, device) {
1158
1210
  if (activeSocket === socket)
1159
1211
  activeConnectionId = '';
1160
1212
  resumed.clear();
1161
- if (code === 1008 && reason.toString() !== 'heartbeat_timeout') {
1213
+ const grantChanged = code === 1012 && reason.toString() === 'grant_changed';
1214
+ if (grantChanged || code === 1008 && reason.toString() !== 'heartbeat_timeout') {
1162
1215
  reconnectGrace.clear();
1163
- for (const child of children.values())
1216
+ for (const [executionId, child] of children) {
1217
+ cancelledExecutions.add(executionId);
1164
1218
  child.terminate();
1219
+ }
1165
1220
  void closeBrowserSessions();
1166
1221
  }
1167
1222
  else if (!stopping)
@@ -1199,8 +1254,9 @@ async function connect(profile, device) {
1199
1254
  }
1200
1255
  if (stopping)
1201
1256
  break;
1202
- operationalLog.write('INFO', {}, 'runner.reconnect_wait', { milliseconds: backoffMs });
1203
- await new Promise(resolve => setTimeout(resolve, backoffMs));
1257
+ const reconnectDelayMs = terminalReconnectDelay(backoffMs);
1258
+ operationalLog.write('INFO', {}, 'runner.reconnect_wait', { milliseconds: reconnectDelayMs });
1259
+ await delay(reconnectDelayMs, undefined, { signal: profile.signal });
1204
1260
  backoffMs = Math.min(backoffMs * 2, 30_000);
1205
1261
  }
1206
1262
  }
@@ -1210,7 +1266,7 @@ async function connect(profile, device) {
1210
1266
  process.off('SIGTERM', stop);
1211
1267
  }
1212
1268
  }
1213
- async function runTerminalCommand(argv) {
1269
+ async function runTerminalCommand(argv, signal) {
1214
1270
  const command = argv[0] || 'help';
1215
1271
  if (command === 'help' || argv.includes('--help')) {
1216
1272
  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]');
@@ -1287,7 +1343,7 @@ async function runTerminalCommand(argv) {
1287
1343
  : `Terminal service already installed (${result.label}).`);
1288
1344
  return;
1289
1345
  }
1290
- const profile = resolveProfile(argv);
1346
+ const profile = { ...resolveProfile(argv), retryReads: command === 'connect', signal };
1291
1347
  let me;
1292
1348
  if (!profile.instance) {
1293
1349
  const currentUser = await api(profile, 'GET', '/me');
@@ -1326,9 +1382,12 @@ async function runTerminalCommand(argv) {
1326
1382
  throw new Error(`Multiple removed terminals match ${name} (${matchingDevices.map(item => item.agentTerminalId).join(', ')}). Select one with --terminal-id.`);
1327
1383
  selectedDevice = matchingDevices[0];
1328
1384
  }
1329
- if (terminalServiceInstalled(selectedDevice.workspace, selectedProject(argv) || getActiveEnvironmentName(), selectedDevice.agentTerminalId)
1330
- || terminalServiceInstalled(selectedDevice.workspace, selectedProject(argv) || getActiveEnvironmentName()))
1331
- throw new Error('Uninstall the selected terminal service before revoking its grant.');
1385
+ const envName = selectedProject(argv) || getActiveEnvironmentName();
1386
+ if (terminalServiceInstalled(selectedDevice.workspace, envName))
1387
+ throw new Error('Uninstall the legacy workspace service before revoking its grant.');
1388
+ if (terminalServiceInstalled(selectedDevice.workspace, envName, selectedDevice.agentTerminalId))
1389
+ uninstallTerminalService({ workspace: selectedDevice.workspace, envName, terminalId: selectedDevice.agentTerminalId,
1390
+ configHome: process.env.XDG_CONFIG_HOME });
1332
1391
  if (listing.devices.some(item => item.agentTerminalId === selectedDevice.agentTerminalId))
1333
1392
  await api(profile, 'POST', `/agents/terminals/${selectedDevice.agentTerminalId}/revoke`);
1334
1393
  await updateStore(current => {
@@ -1391,6 +1450,8 @@ async function runTerminalCommand(argv) {
1391
1450
  }
1392
1451
  console.log(`Pending approval in AI Agents → Terminals: ${device.name} (${device.agentTerminalId}).`);
1393
1452
  }
1453
+ if (profile.realtimeUrl)
1454
+ device = { ...device, realtimeUrl: realtimeUrl(profile.realtimeUrl) };
1394
1455
  if (device.workspace !== workspace) {
1395
1456
  await api(profile, 'POST', `/agents/terminals/${device.agentTerminalId}/workspaces/register`, { path: workspace, name: path.basename(workspace) });
1396
1457
  await updateStore(current => {
@@ -1407,7 +1468,7 @@ async function runTerminalCommand(argv) {
1407
1468
  break;
1408
1469
  if (!grant || grant.status === 'revoked')
1409
1470
  throw new TerminalRunnerFatalError('Terminal grant revoked or missing.');
1410
- await new Promise(resolve => setTimeout(resolve, 2_000));
1471
+ await delay(2_000, undefined, { signal: profile.signal });
1411
1472
  }
1412
1473
  let releaseRunnerLock;
1413
1474
  try {
@@ -1429,14 +1490,28 @@ async function runTerminalCommand(argv) {
1429
1490
  }
1430
1491
  /** Supervisors retry crashes, but a revoked grant or 401/403 needs a human credential/grant change. */
1431
1492
  export async function handleTerminalCommand(argv) {
1493
+ const controller = argv[0] === 'connect' ? new AbortController() : undefined;
1494
+ const stopSetup = () => controller?.abort();
1495
+ if (controller) {
1496
+ process.on('SIGINT', stopSetup);
1497
+ process.on('SIGTERM', stopSetup);
1498
+ }
1432
1499
  try {
1433
- await runTerminalCommand(argv);
1500
+ await runTerminalCommand(argv, controller?.signal);
1434
1501
  }
1435
1502
  catch (error) {
1503
+ if (controller?.signal.aborted)
1504
+ return;
1436
1505
  if (argv.includes('--service-runner') && error instanceof TerminalRunnerFatalError) {
1437
1506
  console.error(error.message);
1438
1507
  return;
1439
1508
  }
1440
1509
  throw error;
1441
1510
  }
1511
+ finally {
1512
+ if (controller) {
1513
+ process.off('SIGINT', stopSetup);
1514
+ process.off('SIGTERM', stopSetup);
1515
+ }
1516
+ }
1442
1517
  }
@@ -810,13 +810,14 @@ export async function buildEndpointsPlan(input) {
810
810
  for (const record of targetEndpoints) {
811
811
  const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
812
812
  const routeKey = endpointRecordRouteKey(record);
813
- if (routeKey) {
813
+ // Soft-deleted records do not own live routes. Keep them in the identity
814
+ // inventory for exact-key restores, matching the API's live-only uniqueness.
815
+ if (routeKey && !record.deletedAt && !record.deletedBy) {
814
816
  targetRouteOwners.set(routeKey, [
815
817
  ...(targetRouteOwners.get(routeKey) || []),
816
818
  {
817
819
  ...(stableKey ? { stableKey } : {}),
818
820
  name: endpointLabel(record, 'unknown'),
819
- deleted: Boolean(record.deletedAt || record.deletedBy),
820
821
  },
821
822
  ]);
822
823
  }
@@ -898,8 +899,7 @@ export async function buildEndpointsPlan(input) {
898
899
  }
899
900
  for (const stableKey of stableKeys) {
900
901
  const collisions = (targetRouteOwners.get(routeKey) || []).filter((owner) => owner.stableKey !== stableKey);
901
- const movingOwners = collisions.filter((owner) => (!owner.deleted
902
- && owner.stableKey
902
+ const movingOwners = collisions.filter((owner) => (owner.stableKey
903
903
  && desiredRoutesByStableKey.has(owner.stableKey)
904
904
  && desiredRoutesByStableKey.get(owner.stableKey) !== routeKey));
905
905
  for (const owner of movingOwners) {
@@ -992,6 +992,13 @@ export async function buildEndpointsPlan(input) {
992
992
  record: deletedTargets[0],
993
993
  componentsById,
994
994
  });
995
+ // Restore happens before configuration update, so the old physical route
996
+ // must also be available even when the desired manifest changes its path.
997
+ const oldRoute = endpointRecordRouteKey(deletedTargets[0]);
998
+ const oldRouteOwners = oldRoute ? targetRouteOwners.get(oldRoute) || [] : [];
999
+ if (oldRouteOwners.length > 0) {
1000
+ restoreSafety.push(`old route ${oldRoute} is owned by ${oldRouteOwners.map(owner => owner.stableKey || owner.name).sort().join(', ')}`);
1001
+ }
995
1002
  if (restoreSafety.length > 0) {
996
1003
  blockers.push(...restoreSafety.map((reason) => `Cannot restore Endpoint "${stableKey}": ${reason}.`));
997
1004
  }
@@ -1515,6 +1522,11 @@ export async function pushEndpoints(input) {
1515
1522
  if (restoreBlockers.length > 0) {
1516
1523
  throw new Error(`restore safety changed after planning: ${restoreBlockers.join('; ')}`);
1517
1524
  }
1525
+ const oldRoute = endpointRecordRouteKey(target);
1526
+ if (oldRoute && liveEndpoints.some(record => !record.deletedAt && !record.deletedBy
1527
+ && endpointRecordRouteKey(record) === oldRoute)) {
1528
+ throw new Error(`restore safety changed after planning: old route ${oldRoute} is now owned by a live endpoint`);
1529
+ }
1518
1530
  await input.client.restoreEndpoint(targetId);
1519
1531
  const restored = unwrapData(await input.client.getEndpoint(targetId));
1520
1532
  const restoredStableKey = readConfiguredResourceMetadataStableKey(restored, input.stableKeyName);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@revoengine/cli",
3
- "version": "1.0.22",
3
+ "version": "1.0.23",
4
4
  "description": "CLI package for the RevoEngine Platform API",
5
5
  "type": "module",
6
6
  "main": "dist/src/index.js",