@revoengine/cli 1.0.13 → 1.0.14

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 (31) hide show
  1. package/README.md +16 -2
  2. package/dist/src/cli.js +4 -0
  3. package/dist/src/client.d.ts +5 -0
  4. package/dist/src/client.js +41 -42
  5. package/dist/src/commands/component.js +26 -25
  6. package/dist/src/commands/migrate.js +10 -0
  7. package/dist/src/commands/terminal-browser.d.ts +40 -6
  8. package/dist/src/commands/terminal-browser.js +480 -19
  9. package/dist/src/commands/terminal-image.js +59 -1
  10. package/dist/src/commands/terminal-operational-log.d.ts +18 -0
  11. package/dist/src/commands/terminal-operational-log.js +119 -0
  12. package/dist/src/commands/terminal-policy.d.ts +23 -0
  13. package/dist/src/commands/terminal-policy.js +48 -0
  14. package/dist/src/commands/terminal-pty.d.ts +4 -0
  15. package/dist/src/commands/terminal-pty.js +39 -0
  16. package/dist/src/commands/terminal-reconnect-grace.d.ts +11 -0
  17. package/dist/src/commands/terminal-reconnect-grace.js +29 -0
  18. package/dist/src/commands/terminal-sandbox.d.ts +5 -1
  19. package/dist/src/commands/terminal-sandbox.js +19 -5
  20. package/dist/src/commands/terminal-secure-browser.d.ts +25 -0
  21. package/dist/src/commands/terminal-secure-browser.js +58 -0
  22. package/dist/src/commands/terminal.d.ts +5 -2
  23. package/dist/src/commands/terminal.js +259 -44
  24. package/dist/src/migration.js +10 -10
  25. package/dist/src/request-queue.d.ts +20 -0
  26. package/dist/src/request-queue.js +80 -0
  27. package/dist/src/resource-inventory.js +9 -10
  28. package/dist/src/resource-syncs/endpoint-sync.js +12 -46
  29. package/dist/src/types.d.ts +2 -0
  30. package/package.json +4 -3
  31. package/scripts/ensure-pty-helper.mjs +9 -0
@@ -4,14 +4,18 @@ import path from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
  import { createHash, randomBytes, randomUUID } from 'node:crypto';
6
6
  import { spawn } from 'node:child_process';
7
- import * as pty from 'node-pty';
8
7
  import WebSocket from 'ws';
9
8
  import { getActiveEnvironmentName, getConfigDir, getEnvironmentProfile, loadStoredConfig, resolveRuntimeConfig } from "../config.js";
10
9
  import { promptConfirm } from "../prompt.js";
11
10
  import { installTerminalService, terminalServiceInstalled, uninstallTerminalService } from "./terminal-service.js";
12
- import { sandboxCommand, shellQuote, requiresElevatedCommand } from "./terminal-sandbox.js";
13
- import { runBrowserAction } from "./terminal-browser.js";
11
+ import { createSandboxScratchDirectory, isTerminalSandbox, sandboxCommand, shellQuote, requiresElevatedCommand } from "./terminal-sandbox.js";
12
+ import { executionPolicyDeadline, validateExecutePolicy } from "./terminal-policy.js";
13
+ import { closeBrowserSessions, fillBrowserSecret, hasBrowserSessions, runBrowserAction, validateBrowserActionInput } from "./terminal-browser.js";
14
14
  import { uploadWorkspaceImages } from "./terminal-image.js";
15
+ import { ensurePtyHelperExecutable, normalizePtyStartError } from "./terminal-pty.js";
16
+ import { TerminalReconnectGrace } from "./terminal-reconnect-grace.js";
17
+ import { TerminalOperationalLog } from "./terminal-operational-log.js";
18
+ import { createSecureBrowserIdentity, decryptSecureBrowserInput } from "./terminal-secure-browser.js";
15
19
  export const MAX_TERMINAL_PROCESS_MS = 59 * 60_000;
16
20
  const configDir = getConfigDir;
17
21
  const runnerConfig = () => path.join(configDir(), 'runner.json');
@@ -19,6 +23,15 @@ const MAX_MODEL_OUTPUT_BYTES = 100_000;
19
23
  const MAX_LOCAL_LOG_BYTES = 10_000_000;
20
24
  const OUTPUT_FRAME_CHARS = 1_000;
21
25
  const LOG_RETENTION_MS = 24 * 60 * 60 * 1_000;
26
+ const OPERATIONAL_ERROR_CODES = new Set([
27
+ 'browser_binary_unavailable', 'browser_cancelled', 'browser_failed', 'browser_localhost_only',
28
+ 'browser_local_network_guard_unavailable',
29
+ 'browser_session_missing', 'browser_session_limit', 'browser_selector_missing', 'browser_selector_ambiguous',
30
+ 'browser_secret_input_requires_secure_reference', 'browser_full_page_too_large',
31
+ 'browser_element_too_large', 'browser_screenshot_too_large', 'browser_output_outside_workspace',
32
+ 'browser_image_upload_unavailable', 'destructive_command_requires_approval',
33
+ 'pty_unavailable', 'sandbox_unavailable',
34
+ ]);
22
35
  const CHILD_ENV_KEYS = ['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM'];
23
36
  export function childEnvironment(source) {
24
37
  const safe = {};
@@ -28,6 +41,10 @@ export function childEnvironment(source) {
28
41
  return safe;
29
42
  }
30
43
  function logDirectory() { return path.join(configDir(), 'runner-logs'); }
44
+ function operationalErrorCode(error) {
45
+ const message = error instanceof Error ? error.message : '';
46
+ return OPERATIONAL_ERROR_CODES.has(message) ? message : 'internal_error';
47
+ }
31
48
  function pruneLogs(directory) {
32
49
  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
33
50
  for (const name of fs.readdirSync(directory)) {
@@ -173,13 +190,16 @@ function sendResult(socket, frame) {
173
190
  export async function runCommand(input, onDone, onChunk) {
174
191
  const workdir = resolveWorkspaceDirectory(input.workspace, input.workdir);
175
192
  const sandbox = input.sandbox || 'workspace';
193
+ if (input.policyDeadlineMs != null && (!Number.isSafeInteger(input.policyDeadlineMs)
194
+ || input.policyDeadlineMs <= Date.now()))
195
+ throw new Error('terminal_policy_expired');
176
196
  if (sandbox !== 'unrestricted' && requiresElevatedCommand(input.cmd))
177
197
  throw new Error('destructive_command_requires_approval');
178
- const scratch = sandbox !== 'unrestricted' ? fs.mkdtempSync(path.join(os.tmpdir(), 'revo-terminal-')) : undefined;
198
+ const scratch = sandbox !== 'unrestricted' ? createSandboxScratchDirectory() : undefined;
179
199
  const scratchRoot = scratch ? fs.realpathSync(scratch) : undefined;
180
200
  let launch;
181
201
  try {
182
- launch = sandboxCommand(input.workspace, workdir, input.cmd, sandbox, process.platform, scratch, [], input.networkAllowed !== false);
202
+ launch = sandboxCommand(input.workspace, workdir, input.cmd, sandbox, process.platform, scratch, [], input.networkAccess || 'none');
183
203
  }
184
204
  catch (error) {
185
205
  if (scratch)
@@ -205,21 +225,25 @@ export async function runCommand(input, onDone, onChunk) {
205
225
  let child;
206
226
  let terminal;
207
227
  try {
208
- if (tty)
228
+ if (tty) {
229
+ ensurePtyHelperExecutable();
230
+ const pty = await import('node-pty');
209
231
  terminal = pty.spawn(launch.file, launch.args, {
210
232
  cwd: workdir, env, name: 'xterm-256color', cols: input.cols || 80, rows: input.rows || 24,
211
233
  });
212
- else
234
+ }
235
+ else {
213
236
  child = spawn(launch.file, launch.args, {
214
237
  cwd: workdir, detached: true, stdio: ['pipe', 'pipe', 'pipe'], env,
215
238
  });
239
+ }
216
240
  }
217
241
  catch (error) {
218
242
  if (logFd !== undefined)
219
243
  fs.closeSync(logFd);
220
244
  if (scratch)
221
245
  fs.rmSync(scratch, { recursive: true, force: true });
222
- throw error;
246
+ throw tty ? normalizePtyStartError(error) : error;
223
247
  }
224
248
  let stdout = '';
225
249
  let stderr = '';
@@ -228,6 +252,7 @@ export async function runCommand(input, onDone, onChunk) {
228
252
  let truncated = false;
229
253
  let logTruncated = logFd === undefined;
230
254
  let timedOut = false;
255
+ let policyExpired = false;
231
256
  let finished = false;
232
257
  const pid = child?.pid || terminal?.pid;
233
258
  const terminate = () => {
@@ -258,6 +283,12 @@ export async function runCommand(input, onDone, onChunk) {
258
283
  hardStop.unref?.();
259
284
  };
260
285
  const timer = setTimeout(() => { timedOut = true; terminate(); }, Math.min(Math.max(input.timeoutMs, 1_000), MAX_TERMINAL_PROCESS_MS));
286
+ const policyTimer = input.policyDeadlineMs == null ? undefined : setTimeout(() => {
287
+ if (finished)
288
+ return;
289
+ policyExpired = true;
290
+ terminate();
291
+ }, Math.max(0, input.policyDeadlineMs - Date.now()));
261
292
  const append = (chunk, kind) => {
262
293
  const logPart = chunk.subarray(0, Math.max(0, MAX_LOCAL_LOG_BYTES - logBytes));
263
294
  if (logPart.length && logFd !== undefined) {
@@ -306,6 +337,8 @@ export async function runCommand(input, onDone, onChunk) {
306
337
  return;
307
338
  finished = true;
308
339
  clearTimeout(timer);
340
+ if (policyTimer)
341
+ clearTimeout(policyTimer);
309
342
  if (scratch) {
310
343
  try {
311
344
  fs.rmSync(scratch, { recursive: true, force: true });
@@ -320,9 +353,11 @@ export async function runCommand(input, onDone, onChunk) {
320
353
  logTruncated = true;
321
354
  }
322
355
  }
323
- onDone({ executed: !error, exitCode: timedOut && exitCode === 0 ? null : exitCode,
324
- stdout, stderr: error ? `${stderr}\n${error.message}` : stderr,
325
- timedOut, truncated, logTruncated, logPath: logFd === undefined ? '' : logPath });
356
+ onDone({ executed: !error, exitCode: (timedOut || policyExpired) && exitCode === 0 ? null : exitCode,
357
+ stdout, stderr: [stderr, error?.message, policyExpired ? 'terminal_policy_expired' : null]
358
+ .filter(Boolean).join('\n'),
359
+ timedOut, truncated, logTruncated, logPath: logFd === undefined ? '' : logPath,
360
+ ...(policyExpired ? { policyExpired: true } : {}) });
326
361
  };
327
362
  child?.on('close', code => finish(code));
328
363
  child?.on('error', error => finish(null, error));
@@ -343,13 +378,16 @@ export async function runCommand(input, onDone, onChunk) {
343
378
  export function runWorkspacePatch(input, onDone) {
344
379
  if (Buffer.byteLength(input.patch) > 64_000)
345
380
  throw new Error('Patch exceeds 64 KB.');
381
+ if (input.policyDeadlineMs != null && (!Number.isSafeInteger(input.policyDeadlineMs)
382
+ || input.policyDeadlineMs <= Date.now()))
383
+ throw new Error('terminal_policy_expired');
346
384
  const workerJs = fileURLToPath(new URL('./terminal-patch-worker.js', import.meta.url));
347
385
  const worker = fs.existsSync(workerJs) ? workerJs : fileURLToPath(new URL('./terminal-patch-worker.ts', import.meta.url));
348
386
  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'revo-terminal-patch-'));
349
387
  let launch;
350
388
  try {
351
389
  const command = [process.execPath, worker, input.workspace, String(input.allowDelete)].map(shellQuote).join(' ');
352
- launch = sandboxCommand(input.workspace, input.workspace, command, 'workspace', process.platform, scratch, [path.dirname(worker)]);
390
+ launch = sandboxCommand(input.workspace, input.workspace, command, 'workspace', process.platform, scratch, [path.dirname(worker)], 'none');
353
391
  }
354
392
  catch (error) {
355
393
  fs.rmSync(scratch, { recursive: true, force: true });
@@ -361,6 +399,7 @@ export function runWorkspacePatch(input, onDone) {
361
399
  let stderr = '';
362
400
  let finished = false;
363
401
  let timedOut = false;
402
+ let policyExpired = false;
364
403
  const timer = setTimeout(() => {
365
404
  timedOut = true;
366
405
  if (child.pid)
@@ -369,6 +408,14 @@ export function runWorkspacePatch(input, onDone) {
369
408
  }
370
409
  catch { /* exited */ }
371
410
  }, 60_000);
411
+ const policyTimer = input.policyDeadlineMs == null ? undefined : setTimeout(() => {
412
+ policyExpired = true;
413
+ if (child.pid)
414
+ try {
415
+ process.kill(-child.pid, 'SIGKILL');
416
+ }
417
+ catch { /* exited */ }
418
+ }, Math.max(0, input.policyDeadlineMs - Date.now()));
372
419
  child.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf8').slice(0, 4_000 - stdout.length); });
373
420
  child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8').slice(0, 4_000 - stderr.length); });
374
421
  child.stdin?.on('error', () => { });
@@ -378,18 +425,25 @@ export function runWorkspacePatch(input, onDone) {
378
425
  return;
379
426
  finished = true;
380
427
  clearTimeout(timer);
428
+ if (policyTimer)
429
+ clearTimeout(policyTimer);
381
430
  try {
382
431
  fs.rmSync(scratch, { recursive: true, force: true });
383
432
  }
384
433
  catch { /* temporary cleanup */ }
385
- onDone({ executed: !error, exitCode: code, stdout,
386
- stderr: error ? `${stderr}\n${error.message}` : stderr, timedOut });
434
+ onDone({ executed: !error, exitCode: policyExpired ? null : code, stdout,
435
+ stderr: [stderr, error?.message, policyExpired ? 'terminal_policy_expired' : null]
436
+ .filter(Boolean).join('\n'), timedOut });
387
437
  };
388
438
  child.on('close', code => finish(code));
389
439
  child.on('error', error => finish(null, error));
390
440
  return child;
391
441
  }
392
442
  async function connect(profile, device) {
443
+ const logDeviceId = /^[A-Za-z0-9_-]{1,128}$/u.test(device.agentTerminalId)
444
+ ? device.agentTerminalId : createHash('sha256').update(device.agentTerminalId).digest('hex');
445
+ const operationalLog = new TerminalOperationalLog(path.join(configDir(), 'logs', 'terminal', logDeviceId));
446
+ operationalLog.write('INFO', {}, 'runner.started');
393
447
  let backoffMs = 1_000;
394
448
  let stopping = false;
395
449
  let activeSocket;
@@ -399,8 +453,17 @@ async function connect(profile, device) {
399
453
  const cancelledExecutions = new Set();
400
454
  const outputByExecution = new Map();
401
455
  const completed = new Map();
456
+ const traces = new Map();
457
+ const secureRequests = new Map();
402
458
  const resumed = new Set();
403
- let reconnectGrace;
459
+ const reconnectGrace = new TerminalReconnectGrace(() => {
460
+ for (const child of children.values())
461
+ child.terminate();
462
+ void closeBrowserSessions();
463
+ });
464
+ let minimumPolicyGrantRevision = 0;
465
+ let policyRevisionUnavailable = false;
466
+ let securePolicyEpoch = 0;
404
467
  const sendCurrent = (frame) => {
405
468
  if (activeConnectionId && activeSocket?.readyState === WebSocket.OPEN)
406
469
  send(activeSocket, { ...frame, connectionId: activeConnectionId });
@@ -415,9 +478,10 @@ async function connect(profile, device) {
415
478
  sendCurrent({ type: 'result', executionId, ...result });
416
479
  };
417
480
  const stop = () => {
481
+ operationalLog.write('INFO', {}, 'runner.stopping', { activeExecutions: children.size });
418
482
  stopping = true;
419
- if (reconnectGrace)
420
- clearTimeout(reconnectGrace);
483
+ void closeBrowserSessions();
484
+ reconnectGrace.clear();
421
485
  if (activeSocket?.readyState === WebSocket.CONNECTING)
422
486
  activeSocket.terminate();
423
487
  else
@@ -431,6 +495,7 @@ async function connect(profile, device) {
431
495
  while (!stopping) {
432
496
  try {
433
497
  await new Promise((resolve, reject) => {
498
+ const secureIdentity = createSecureBrowserIdentity();
434
499
  const socket = new WebSocket(device.realtimeUrl, {
435
500
  headers: { Authorization: `Bearer ${profile.token}`,
436
501
  ...(profile.instance ? { instance: profile.instance } : {}) },
@@ -444,23 +509,31 @@ async function connect(profile, device) {
444
509
  let incoming = Promise.resolve();
445
510
  socket.on('open', () => send(socket, { type: 'hello', protocol: 1, agentTerminalId: device.agentTerminalId,
446
511
  secret: device.secret, capabilities: ['workspace_sandbox_v1', 'workspace_network_v1', 'network_policy_v1',
447
- 'apply_patch_v1', 'stdin_v1', 'pty_v1', 'browser_v1', 'browser_local_v1', 'save_image_v1',
448
- ...(process.platform === 'darwin' ? ['localhost_shell_v1'] : [])] }));
512
+ 'terminal_policy_v2',
513
+ 'apply_patch_v1', 'stdin_v1', 'pty_v1', 'browser_v1', 'browser_session_v1', 'browser_forms_v1',
514
+ 'browser_local_v1', 'browser_once_v1', 'browser_secure_input_v1', 'save_image_v1',
515
+ ...(process.platform === 'darwin' ? ['localhost_shell_v1'] : [])],
516
+ secureBrowserPublicKey: secureIdentity.publicKey, secureBrowserKeyId: secureIdentity.keyId }));
449
517
  socket.on('message', raw => {
450
518
  incoming = incoming.then(async () => {
451
519
  if (stopping || socket.readyState !== WebSocket.OPEN)
452
520
  return;
453
521
  const frame = JSON.parse(raw.toString());
454
522
  if (frame.type === 'ready' && frame.connectionId) {
523
+ securePolicyEpoch++;
455
524
  connectionId = frame.connectionId;
456
525
  activeConnectionId = connectionId;
457
526
  workspace = frame.workspace || device.workspace;
458
- backoffMs = 1_000;
459
- if (reconnectGrace) {
460
- clearTimeout(reconnectGrace);
461
- reconnectGrace = undefined;
527
+ if (Number.isSafeInteger(frame.policyGrantRevision) && frame.policyGrantRevision >= 0) {
528
+ minimumPolicyGrantRevision = Math.max(minimumPolicyGrantRevision, frame.policyGrantRevision);
529
+ policyRevisionUnavailable = false;
462
530
  }
531
+ else
532
+ policyRevisionUnavailable = true;
533
+ backoffMs = 1_000;
534
+ reconnectGrace.clear();
463
535
  console.log(`Connected ${device.name} (${device.agentTerminalId}).`);
536
+ operationalLog.write('INFO', {}, 'socket.ready', { resumedExecutions: children.size + completed.size });
464
537
  for (const executionId of new Set([...children.keys(), ...completed.keys()]))
465
538
  send(socket, { type: 'resume', connectionId, executionId });
466
539
  heartbeat = setInterval(() => {
@@ -476,6 +549,66 @@ async function connect(profile, device) {
476
549
  lastHeartbeat = Date.now();
477
550
  return;
478
551
  }
552
+ if (frame.type === 'policy_revoked') {
553
+ if (frame.connectionId !== connectionId)
554
+ return;
555
+ securePolicyEpoch++;
556
+ if (Number.isSafeInteger(frame.policyGrantRevision) && frame.policyGrantRevision >= 0)
557
+ minimumPolicyGrantRevision = Math.max(minimumPolicyGrantRevision, frame.policyGrantRevision);
558
+ else
559
+ policyRevisionUnavailable = true;
560
+ operationalLog.write('WARN', {}, 'terminal.policy_revoked', { activeExecutions: children.size });
561
+ for (const [executionId, child] of children) {
562
+ cancelledExecutions.add(executionId);
563
+ child.terminate();
564
+ }
565
+ await closeBrowserSessions();
566
+ return;
567
+ }
568
+ if (frame.type === 'secure_browser_input') {
569
+ if (frame.connectionId !== connectionId || frame.agentTerminalId !== device.agentTerminalId
570
+ || typeof frame.requestId !== 'string' || !/^[a-f0-9-]{36}$/iu.test(frame.requestId))
571
+ return;
572
+ const secureRequestId = frame.requestId;
573
+ const requestEpoch = securePolicyEpoch;
574
+ const trace = { assistantThreadId: frame.threadId };
575
+ const errorCodes = new Set(['secure_input_invalid', 'secure_input_session_missing',
576
+ 'secure_input_origin_changed', 'secure_input_selector_missing',
577
+ 'secure_input_not_secret_control', 'secure_input_fill_failed']);
578
+ void (async () => {
579
+ try {
580
+ const now = Date.now();
581
+ for (const [requestId, seenAt] of secureRequests)
582
+ if (now - seenAt > 5 * 60_000)
583
+ secureRequests.delete(requestId);
584
+ if (secureRequests.has(secureRequestId))
585
+ throw new Error('secure_input_replayed');
586
+ secureRequests.set(secureRequestId, now);
587
+ if (secureRequests.size > 512)
588
+ secureRequests.delete(secureRequests.keys().next().value);
589
+ const envelope = frame;
590
+ const value = decryptSecureBrowserInput(envelope, secureIdentity);
591
+ await fillBrowserSecret({ browserSessionId: envelope.browserSessionId,
592
+ origin: envelope.origin, selector: envelope.selector,
593
+ expiresAt: envelope.expiresAt, value,
594
+ isAuthorized: () => requestEpoch === securePolicyEpoch && !stopping
595
+ && socket.readyState === WebSocket.OPEN && activeConnectionId === connectionId });
596
+ if (requestEpoch !== securePolicyEpoch || socket.readyState !== WebSocket.OPEN)
597
+ throw new Error('secure_input_session_missing');
598
+ operationalLog.write('INFO', trace, 'browser.secure_fill_completed');
599
+ send(socket, { type: 'secure_browser_input_result', connectionId,
600
+ requestId: secureRequestId, status: 'filled' });
601
+ }
602
+ catch (error) {
603
+ const errorCode = error instanceof Error && errorCodes.has(error.message)
604
+ ? error.message : 'secure_input_failed';
605
+ operationalLog.write('WARN', trace, 'browser.secure_fill_failed', { errorCode });
606
+ send(socket, { type: 'secure_browser_input_result', connectionId,
607
+ requestId: secureRequestId, status: 'error', errorCode });
608
+ }
609
+ })();
610
+ return;
611
+ }
479
612
  if (frame.connectionId !== connectionId || !frame.executionId)
480
613
  return;
481
614
  if (frame.type === 'resumed') {
@@ -484,16 +617,20 @@ async function connect(profile, device) {
484
617
  return;
485
618
  }
486
619
  if (frame.type === 'result_ack' || frame.type === 'resume_rejected') {
487
- if (frame.type === 'resume_rejected')
620
+ if (frame.type === 'resume_rejected') {
621
+ operationalLog.write('WARN', traces.get(frame.executionId) || { executionId: frame.executionId }, 'execution.resume_rejected');
488
622
  children.get(frame.executionId)?.terminate();
623
+ }
489
624
  completed.delete(frame.executionId);
490
625
  outputByExecution.delete(frame.executionId);
491
626
  resumed.delete(frame.executionId);
627
+ traces.delete(frame.executionId);
492
628
  return;
493
629
  }
494
630
  if (frame.type === 'cancel') {
495
631
  const child = children.get(frame.executionId);
496
632
  if (child) {
633
+ operationalLog.write('WARN', traces.get(frame.executionId) || { executionId: frame.executionId }, 'execution.cancel_requested');
497
634
  cancelledExecutions.add(frame.executionId);
498
635
  child.terminate();
499
636
  }
@@ -503,6 +640,7 @@ async function connect(profile, device) {
503
640
  const child = children.get(frame.executionId);
504
641
  if (child && typeof frame.chars === 'string' && Buffer.byteLength(frame.chars) <= 8_192
505
642
  && typeof frame.closeStdin === 'boolean') {
643
+ operationalLog.write('DEBUG', traces.get(frame.executionId) || { executionId: frame.executionId }, 'execution.stdin', { bytes: Buffer.byteLength(frame.chars), close: frame.closeStdin });
506
644
  if (frame.closeStdin)
507
645
  child.closeStdin(frame.chars);
508
646
  else if (frame.chars)
@@ -519,33 +657,67 @@ async function connect(profile, device) {
519
657
  }
520
658
  if (frame.type !== 'execute')
521
659
  return;
660
+ if (policyRevisionUnavailable || !Number.isSafeInteger(frame.policyGrantRevision)
661
+ || frame.policyGrantRevision < minimumPolicyGrantRevision) {
662
+ sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
663
+ executed: false, exitCode: null, stdout: '', stderr: 'terminal_permission_changed', timedOut: false });
664
+ return;
665
+ }
522
666
  if (children.has(frame.executionId) || completed.has(frame.executionId)) {
667
+ operationalLog.write('DEBUG', traces.get(frame.executionId) || { executionId: frame.executionId }, 'execution.duplicate');
523
668
  send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
524
669
  return;
525
670
  }
526
671
  const operation = frame.operation || 'shell';
672
+ const trace = { assistantThreadId: frame.assistantThreadId,
673
+ assistantMessageId: frame.assistantMessageId, executionId: frame.executionId };
674
+ let validBrowserPayload = false;
675
+ if (operation === 'browser' && typeof frame.url === 'string' && frame.url.length <= 2_048
676
+ && typeof frame.browserSessionId === 'string' && frame.browserAction) {
677
+ try {
678
+ validateBrowserActionInput({ url: frame.url, action: frame.browserAction,
679
+ workspace, browserSessionId: frame.browserSessionId, selector: frame.selector,
680
+ width: frame.width, height: frame.height, value: frame.value, checked: frame.checked,
681
+ key: frame.key, deltaY: frame.deltaY, state: frame.state,
682
+ waitTimeoutMs: frame.waitTimeoutMs, capture: frame.capture, clip: frame.clip,
683
+ localOnly: frame.browserLocalOnly === true });
684
+ validBrowserPayload = true;
685
+ }
686
+ catch { /* invalid_command result below */ }
687
+ }
527
688
  const validPayload = operation === 'apply_patch'
528
689
  ? typeof frame.patch === 'string' && Buffer.byteLength(frame.patch) <= 64_000
529
- : operation === 'browser' ? typeof frame.url === 'string' && frame.url.length <= 2_048
530
- && ['navigate', 'dom', 'screenshot'].includes(frame.browserAction || '')
690
+ : operation === 'browser' ? validBrowserPayload
531
691
  : operation === 'save_image' ? Array.isArray(frame.files) && frame.files.length > 0 && frame.files.length <= 32
532
692
  : operation === 'shell' && typeof frame.cmd === 'string' && !!frame.cmd.trim() && frame.cmd.length <= 8_192;
533
- if (!validPayload || children.size >= 4 || !['workspace', 'workspace-network', 'unrestricted'].includes(frame.sandbox || 'unrestricted')
534
- || frame.networkAllowed === false && frame.sandbox === 'workspace-network'
693
+ if (!validPayload || children.size >= 4 || !isTerminalSandbox(frame.sandbox)
535
694
  || operation === 'apply_patch' && frame.sandbox === 'workspace-network'
536
- || (operation === 'browser' || operation === 'save_image') && (frame.sandbox !== 'workspace-network'
537
- || frame.networkAllowed === false)
695
+ || (operation === 'browser' || operation === 'save_image') && frame.sandbox !== 'workspace-network'
538
696
  || frame.tty === true && (operation !== 'shell' || !Number.isInteger(frame.cols) || !Number.isInteger(frame.rows)
539
697
  || frame.cols < 20 || frame.cols > 240 || frame.rows < 10 || frame.rows > 100)) {
698
+ operationalLog.write('WARN', trace, 'execution.rejected', { operation,
699
+ reason: children.size >= 4 ? 'runner_busy' : 'invalid_command' });
540
700
  sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
541
701
  executed: false, exitCode: null, stdout: '', stderr: children.size >= 4 ? 'runner_busy' : 'invalid_command', timedOut: false });
542
702
  return;
543
703
  }
704
+ const policyError = validateExecutePolicy({ ...frame, operation });
705
+ if (policyError) {
706
+ operationalLog.write('WARN', trace, 'execution.rejected', { operation, reason: policyError });
707
+ sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
708
+ executed: false, exitCode: null, stdout: '', stderr: policyError, timedOut: false });
709
+ return;
710
+ }
544
711
  try {
712
+ traces.set(frame.executionId, trace);
713
+ operationalLog.write('INFO', trace, 'execution.started', { operation, sandbox: frame.sandbox });
545
714
  resumed.add(frame.executionId);
546
715
  outputByExecution.set(frame.executionId, []);
547
716
  if (operation === 'save_image') {
548
717
  const controller = new AbortController();
718
+ const policyDeadline = executionPolicyDeadline(frame);
719
+ const policyTimer = policyDeadline == null ? undefined : setTimeout(() => controller.abort(), Math.max(0, policyDeadline - Date.now()));
720
+ policyTimer?.unref?.();
549
721
  const child = { pid: undefined, write: () => undefined,
550
722
  closeStdin: () => undefined, resize: () => undefined,
551
723
  terminate: () => controller.abort() };
@@ -553,16 +725,23 @@ async function connect(profile, device) {
553
725
  activeChildren.add(child);
554
726
  send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
555
727
  void uploadWorkspaceImages(workspace, frame.files, controller.signal).then(count => {
728
+ if (policyTimer)
729
+ clearTimeout(policyTimer);
556
730
  children.delete(frame.executionId);
557
731
  activeChildren.delete(child);
558
732
  completed.set(frame.executionId, { executed: true, exitCode: 0, stdout: `Uploaded ${count} image(s).`, stderr: '' });
733
+ operationalLog.write('INFO', trace, 'execution.completed', { operation, exitCode: 0, images: count });
559
734
  if (resumed.has(frame.executionId))
560
735
  flushExecution(frame.executionId);
561
736
  }).catch(error => {
737
+ if (policyTimer)
738
+ clearTimeout(policyTimer);
562
739
  children.delete(frame.executionId);
563
740
  activeChildren.delete(child);
564
741
  completed.set(frame.executionId, { executed: false, exitCode: null, stdout: '',
565
742
  stderr: error instanceof Error ? error.message : 'image_upload_failed' });
743
+ operationalLog.write('ERROR', trace, 'execution.failed', { operation,
744
+ errorCode: 'image_upload_failed' });
566
745
  if (resumed.has(frame.executionId))
567
746
  flushExecution(frame.executionId);
568
747
  });
@@ -570,6 +749,10 @@ async function connect(profile, device) {
570
749
  }
571
750
  if (operation === 'browser') {
572
751
  const controller = new AbortController();
752
+ const policyDeadline = executionPolicyDeadline(frame);
753
+ const policyTimer = policyDeadline == null ? undefined : setTimeout(() => controller.abort(), Math.max(0, policyDeadline - Date.now()));
754
+ policyTimer?.unref?.();
755
+ let actionAttempted = false;
573
756
  const child = { pid: undefined, write: () => undefined,
574
757
  closeStdin: () => undefined, resize: () => undefined,
575
758
  terminate: () => controller.abort() };
@@ -577,27 +760,47 @@ async function connect(profile, device) {
577
760
  activeChildren.add(child);
578
761
  send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
579
762
  void runBrowserAction({ url: frame.url, action: frame.browserAction, workspace,
763
+ browserSessionId: frame.browserSessionId, onActionAttempt: () => { actionAttempted = true; },
580
764
  selector: frame.selector, width: frame.width, height: frame.height,
581
- localOnly: frame.browserLocalOnly === true, signal: controller.signal })
765
+ value: frame.value, checked: frame.checked, key: frame.key, deltaY: frame.deltaY,
766
+ state: frame.state, waitTimeoutMs: frame.waitTimeoutMs,
767
+ capture: frame.capture, clip: frame.clip,
768
+ localOnly: frame.browserLocalOnly === true,
769
+ networkAccessExpiresAt: frame.networkAccessExpiresAt,
770
+ networkAccessOnce: frame.networkAccessOnce,
771
+ signal: controller.signal })
582
772
  .then(async (browserResult) => {
583
773
  if (frame.browserAction === 'screenshot') {
584
774
  if (!browserResult.screenshotPath || frame.files?.length !== 1)
585
775
  throw new Error('browser_image_upload_unavailable');
586
776
  await uploadWorkspaceImages(workspace, [{ ...frame.files[0], path: browserResult.screenshotPath }], controller.signal);
587
777
  }
778
+ if (policyTimer)
779
+ clearTimeout(policyTimer);
588
780
  children.delete(frame.executionId);
589
781
  activeChildren.delete(child);
590
782
  completed.set(frame.executionId, { executed: true, exitCode: 0,
591
783
  stdout: browserResult.dom, stderr: '', screenshotPath: browserResult.screenshotPath || null,
784
+ pageUrl: browserResult.pageUrl,
592
785
  cancelled: cancelledExecutions.delete(frame.executionId) });
786
+ operationalLog.write('INFO', trace, 'execution.completed', { operation,
787
+ browserAction: frame.browserAction, exitCode: 0, screenshot: frame.browserAction === 'screenshot' });
593
788
  if (resumed.has(frame.executionId))
594
789
  flushExecution(frame.executionId);
595
790
  }).catch(error => {
791
+ if (policyTimer)
792
+ clearTimeout(policyTimer);
596
793
  children.delete(frame.executionId);
597
794
  activeChildren.delete(child);
598
- completed.set(frame.executionId, { executed: false, exitCode: null, stdout: '',
599
- stderr: error instanceof Error ? error.message : 'browser_failed',
795
+ const code = error instanceof Error && /^[a-z][a-z_]+$/u.test(error.message)
796
+ ? error.message : 'browser_failed';
797
+ completed.set(frame.executionId, { executed: actionAttempted, exitCode: null, stdout: '',
798
+ stderr: actionAttempted ? 'browser_action_outcome_unknown' : code,
600
799
  cancelled: cancelledExecutions.delete(frame.executionId) });
800
+ operationalLog.write('ERROR', trace, 'execution.failed', { operation,
801
+ browserAction: frame.browserAction,
802
+ errorCode: actionAttempted ? 'browser_action_outcome_unknown' : operationalErrorCode(error),
803
+ executed: actionAttempted });
601
804
  if (resumed.has(frame.executionId))
602
805
  flushExecution(frame.executionId);
603
806
  });
@@ -605,10 +808,12 @@ async function connect(profile, device) {
605
808
  }
606
809
  if (operation === 'apply_patch') {
607
810
  const patchChild = runWorkspacePatch({ patch: frame.patch, workspace,
608
- allowDelete: (frame.sandbox || 'unrestricted') === 'unrestricted' }, result => {
811
+ allowDelete: frame.sandbox === 'unrestricted',
812
+ policyDeadlineMs: executionPolicyDeadline(frame) }, result => {
609
813
  children.delete(frame.executionId);
610
814
  activeChildren.delete(child);
611
815
  completed.set(frame.executionId, { ...result, cancelled: cancelledExecutions.delete(frame.executionId) });
816
+ operationalLog.write(result.exitCode === 0 ? 'INFO' : 'ERROR', trace, result.exitCode === 0 ? 'execution.completed' : 'execution.failed', { operation, exitCode: result.exitCode ?? 'none', executed: result.executed });
612
817
  if (resumed.has(frame.executionId))
613
818
  flushExecution(frame.executionId);
614
819
  });
@@ -628,7 +833,8 @@ async function connect(profile, device) {
628
833
  return;
629
834
  }
630
835
  const child = await runCommand({ cmd: frame.cmd, workdir: frame.workdir || workspace,
631
- workspace, sandbox: frame.sandbox || 'unrestricted', networkAllowed: frame.networkAllowed,
836
+ workspace, sandbox: frame.sandbox, networkAccess: frame.networkAccess,
837
+ policyDeadlineMs: executionPolicyDeadline(frame),
632
838
  timeoutMs: frame.timeoutMs || 60_000, tty: frame.tty,
633
839
  cols: frame.cols, rows: frame.rows,
634
840
  executionId: frame.executionId }, result => {
@@ -637,6 +843,8 @@ async function connect(profile, device) {
637
843
  const { stdout, stderr, ...completion } = result;
638
844
  completed.set(frame.executionId, { ...completion,
639
845
  cancelled: cancelledExecutions.delete(frame.executionId), stdout: '', stderr: '' });
846
+ operationalLog.write(completion.exitCode === 0 ? 'INFO' : 'ERROR', trace, completion.exitCode === 0 ? 'execution.completed' : 'execution.failed', { operation, exitCode: completion.exitCode ?? 'none', executed: completion.executed,
847
+ timedOut: completion.timedOut, truncated: completion.truncated });
640
848
  if (resumed.has(frame.executionId))
641
849
  sendCurrent({ type: 'result', executionId: frame.executionId,
642
850
  ...completed.get(frame.executionId) });
@@ -655,28 +863,30 @@ async function connect(profile, device) {
655
863
  catch (error) {
656
864
  resumed.delete(frame.executionId);
657
865
  outputByExecution.delete(frame.executionId);
866
+ traces.delete(frame.executionId);
867
+ operationalLog.write('ERROR', trace, 'execution.rejected', { operation,
868
+ errorCode: operationalErrorCode(error) });
658
869
  sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
659
870
  executed: false, exitCode: null, stdout: '', stderr: error instanceof Error ? error.message : 'Command rejected.', timedOut: false });
660
871
  }
661
872
  }).catch(() => socket.terminate());
662
873
  });
663
874
  socket.on('close', (code, reason) => {
875
+ securePolicyEpoch++;
876
+ operationalLog.write(code === 1000 ? 'INFO' : 'WARN', {}, 'socket.closed', { code, activeExecutions: children.size, policyViolation: code === 1008 });
664
877
  if (heartbeat)
665
878
  clearInterval(heartbeat);
666
879
  if (activeSocket === socket)
667
880
  activeConnectionId = '';
668
881
  resumed.clear();
669
882
  if (code === 1008 && reason.toString() !== 'heartbeat_timeout') {
883
+ reconnectGrace.clear();
670
884
  for (const child of children.values())
671
885
  child.terminate();
886
+ void closeBrowserSessions();
672
887
  }
673
- else if (!stopping && children.size) {
674
- reconnectGrace = setTimeout(() => {
675
- for (const child of children.values())
676
- child.terminate();
677
- }, 120_000);
678
- reconnectGrace.unref?.();
679
- }
888
+ else if (!stopping)
889
+ reconnectGrace.start(children.size > 0 || hasBrowserSessions());
680
890
  if (activeSocket === socket)
681
891
  activeSocket = undefined;
682
892
  if (code === 1008 && reason.toString() !== 'heartbeat_timeout')
@@ -684,16 +894,21 @@ async function connect(profile, device) {
684
894
  else
685
895
  resolve();
686
896
  });
687
- socket.on('error', error => { console.error(`Realtime connection: ${error.message}`); });
897
+ socket.on('error', () => {
898
+ operationalLog.write('WARN', {}, 'socket.error');
899
+ console.error('Realtime connection failed; terminal will retry.');
900
+ });
688
901
  });
689
902
  }
690
903
  catch (error) {
691
904
  if (error instanceof Error && error.message.startsWith('Runner rejected by Realtime:'))
692
905
  throw error;
693
- console.error(error);
906
+ operationalLog.write('WARN', {}, 'runner.connect_failed', { errorCode: operationalErrorCode(error) });
907
+ console.error('Terminal connection failed; retrying.');
694
908
  }
695
909
  if (stopping)
696
910
  break;
911
+ operationalLog.write('INFO', {}, 'runner.reconnect_wait', { milliseconds: backoffMs });
697
912
  await new Promise(resolve => setTimeout(resolve, backoffMs));
698
913
  backoffMs = Math.min(backoffMs * 2, 30_000);
699
914
  }