Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

18.1 KB
Raw Blame
import { channel } from 'node:diagnostics_channel';
import { existsSync } from 'node:fs';
import { mkdtemp, rm, access, constants } from 'node:fs/promises';
import { tmpdir, constants as osConstants } from 'node:os';
import { join } from 'node:path';
import { spawn } from '../../lib/childProcess.js';
import { safeChildProcessOptions } from '../../lib/processEnv.js';
import { killWithEscalation } from '../../lib/killWithEscalation.js';
import { browserExecutablePath } from '../../lib/browserConfig.js';
import { isVitestRunner } from '../../lib/runtimeEnv.js';
import { PREVIEW_HOST_RESOLVER_SOCKETS, previewIsolationPlan } from '../../lib/generatedPreviewSandbox.js';
import { createCdpPipeTransport } from './cdpPipe.js';
import { drainBrowserProcessGroup, observeBrowserProcessGroup, signalBrowserProcessGroup } from './browserProcessGroup.js';

// Chrome refuses to run as root with its sandbox on. Only a Vitest worker
// running as root (a root dev/CI container) drops it, matching the test-owned
// Chrome launches in testBrowserCleanup.js; production keeps the sandbox.
const sandboxArgs = () => (isVitestRunner() && process.getuid?.() === 0 ? ['--no-sandbox'] : []);

// Passive test observers receive only exact owned capabilities. No subscriber
// means no persistence, process inspection, or additional lifecycle work.
const lifecycle = channel('portos.composition-browser.lifecycle');
const observe = (event, profile, details) => {
  if (lifecycle.hasSubscribers) lifecycle.publish({ event, profile, ...details });
};
// Raw browser output can hold private paths, so a startup failure names a
// recognized cause instead of copying stderr.
const ROOT_SANDBOX_REFUSAL = /Running as root without --no-sandbox is not supported/;

// Chrome helpers (crashpad, GPU) can still be writing into the profile for a
// moment after the browser's close event, so a recursive rm may lose the race
// with ENOTEMPTY/EBUSY. Retry until the directory is really gone, so a resolved
// close always means the profile no longer exists.
const TRANSIENT_RM = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM', 'EMFILE']);
async function removeProfile(profile, attempts = 20, delayMs = 50) {
  for (let attempt = 1; ; attempt++) {
    try { return await rm(profile, { recursive: true, force: true }); }
    catch (error) {
      if (attempt >= attempts || !TRANSIENT_RM.has(error?.code)) throw error;
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
}

// The preview browser must not inherit API tokens or the database password.
// HOME and PATH stay so Chrome can start; the seatbelt or network namespace
// still denies IP egress.
function previewBrowserEnv() {
  const env = { USER: 'portos-preview' };
  for (const key of ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'MAC_CHROMIUM_TMPDIR', 'LANG', 'LC_ALL', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT']) {
    if (process.env[key]) env[key] = process.env[key];
  }
  return env;
}

async function readPreviewIsolationSupport() {
  const executable = async (path) => access(path, constants.X_OK).then(() => true, () => false);
  return {
    platform: process.platform,
    seatbeltAvailable: process.platform === 'darwin' && await executable('/usr/bin/sandbox-exec'),
    bubblewrapAvailable: process.platform === 'linux' && await executable('/usr/bin/bwrap'),
    hostResolverSockets: PREVIEW_HOST_RESOLVER_SOCKETS.filter((path) => existsSync(path)),
  };
}

function isolationUnavailable(reason) {
  const error = new Error(reason || 'Generated preview isolation is unavailable on this host');
  error.code = 'PREVIEW_ISOLATION_UNAVAILABLE';
  error.status = 503;
  return error;
}

// Only this child/profile belong to the render. Never discover processes by
// name, attach to a user profile, or restart the managed browsing service.
// `isolation: 'legacy'` keeps the render browser's loopback DevTools port.
// Generated previews pass `'required'` and talk CDP over pipes so loopback IP
// can be denied too. `'off'` exists for the egress negative control.
export async function launchCompositionBrowser({
  signal, startupMs = 20000, shutdownMs = 5000, isolation = 'legacy', support,
} = {}) {
  signal?.throwIfAborted();
  const piped = isolation !== 'legacy';
  const ownsProcessGroup = process.platform !== 'win32';
  const { loadConfig } = await import('../browserService.js');
  const executable = browserExecutablePath(await loadConfig());
  signal?.throwIfAborted();
  if (isolation === 'required' || isolation === 'os') {
    const facts = support || await readPreviewIsolationSupport();
    const probe = previewIsolationPlan({ ...facts, executable, profileDir: '/tmp/portos-preview', isolation });
    if (!probe.supported) throw isolationUnavailable(probe.reason);
  } else if (isolation !== 'legacy' && isolation !== 'off') {
    throw isolationUnavailable('Unknown preview isolation mode');
  }
  const profile = await mkdtemp(join(tmpdir(), 'portos-composition-browser-'));
  observe('allocated', profile);
  let proc;
  let transport;
  let startupPipeError;
  let rejectStartupPipe;
  // Own pipe errors across the startup-to-CDP handoff. The CDP client also
  // subscribes, so this listener must not consume or replace its error path.
  const onPipeError = error => { startupPipeError ??= error; rejectStartupPipe?.(error); };
  let exited = false;
  let closed = false;
  let spawned = false;
  let closing;
  let profileCleanup;
  let terminationStarted;
  let closeDeadlineExpired = false;
  // Fixed-size observations from this retained child only. Observation
  // timestamps are monotonic milliseconds since ownership began.
  const observedSince = performance.now();
  const observed = { spawnMs: null, exitMs: null, closeMs: null, termMs: null, killMs: null };
  const observedMs = () => Math.round(performance.now() - observedSince);
  const groupTermination = { term: 'not-attempted', kill: 'not-attempted', error: 'none', failedSignal: 'none', failedPhase: 'none' };
  const groupObservations = { signal: 'not-requested', deadline: 'not-requested' };
  const observationBudgetMs = Math.min(500, Math.max(1, Math.floor(shutdownMs / 4)));
  const sampleGroup = slot => {
    if (!ownsProcessGroup || !proc?.pid || groupObservations[slot] !== 'not-requested') return;
    const startMs = observedMs();
    groupObservations[slot] = 'pending';
    // Never await a diagnostic at the shutdown boundary or allow its eventual
    // result to replace the original close verdict. At most two bounded reads.
    observeBrowserProcessGroup(proc.pid, observationBudgetMs)
      .then(facts => { groupObservations[slot] = `startMs:${startMs}|endMs:${observedMs()}|${facts}`; })
      .catch(() => { groupObservations[slot] = 'unavailable'; });
  };
  const termination = { term: 'not-attempted', kill: 'not-attempted', error: 'none' };
  // Never interpolate arbitrary child properties: only allowlisted status values.
  const childStatus = () => ({
    exitCode: proc?.exitCode == null ? 'none' : Number.isSafeInteger(proc.exitCode) ? proc.exitCode : 'other',
    signalCode: proc?.signalCode == null ? 'none'
      : typeof proc.signalCode === 'string' && Object.hasOwn(osConstants.signals, proc.signalCode) ? proc.signalCode : 'other',
  });
  // Read by the CDP client when a command fails, before close() changes them.
  const lifecycleFacts = () => ({ childSpawned: spawned, childExited: exited, childClosed: closed, ...childStatus() });
  const safeSignalError = error => ['EPERM', 'ESRCH', 'EINVAL', 'ENOSYS'].includes(error?.code) ? error.code : 'other';
  const cleanupProfile = () => {
    if (!profileCleanup) {
      profileCleanup = (async () => {
        if (ownsProcessGroup && proc?.pid && closed) {
          // Late child close still owns cleanup, without changing the rejected close verdict.
          const deadline = (closeDeadlineExpired ? performance.now() : terminationStarted ?? performance.now()) + shutdownMs;
          await drainBrowserProcessGroup(proc.pid, deadline, Math.min(1000, shutdownMs / 2), groupTermination);
        }
        observe('remove-start', profile);
        await removeProfile(profile);
      })();
      // Observe settlement without replacing the cached promise or its verdict.
      if (lifecycle.hasSubscribers) profileCleanup.then(
        () => observe('remove-resolved', profile),
        error => observe('remove-rejected', profile, { code: TRANSIENT_RM.has(error?.code) || ['EACCES', 'ENOENT'].includes(error?.code) ? error.code : 'other' }),
      );
    }
    return profileCleanup;
  };
  let closeResolve;
  const childClosed = new Promise(resolve => { closeResolve = resolve; });
  const onExit = () => {
    exited = true;
    observed.exitMs ??= observedMs();
    // Chrome helpers may retain inherited stderr after the browser exits.
    // Release our pipe without signaling unrelated or discovered processes.
    proc?.stderr?.destroy();
    if (piped) {
      proc?.stdio?.[3]?.destroy();
      proc?.stdio?.[4]?.destroy();
    }
  };
  const onClose = () => {
    closed = true;
    observed.closeMs ??= observedMs();
    proc?.removeListener('error', onError);
    // A deadline can reject close() before the OS reports exit. Retain ownership
    // until the eventual close event and remove only this child's profile then.
    cleanupProfile().catch(error => console.error(`❌ Composition browser profile cleanup failed (${safeSignalError(error)})`));
    closeResolve();
  };
  // Child 'error' may also be emitted by kill(). Keep a listener until close.
  const onError = error => {
    termination.error = safeSignalError(error);
    if (!spawned && !proc?.pid) { onExit(); onClose(); }
  };
  const signalChild = (name) => {
    // sandbox-exec / bwrap wait on Chrome. Signal the group, then the wrapper,
    // so a helper cannot keep the profile open after close.
    if (ownsProcessGroup && proc?.pid) {
      signalBrowserProcessGroup(proc.pid, name, groupTermination, 'shutdown');
      if (groupTermination.error !== 'none') sampleGroup('signal');
    }
    return proc.kill(name);
  };
  const close = () => closing ??= (async () => {
    signal?.removeEventListener('abort', abort);
    let escalation;
    let deadline;
    let observationTimer;
    try {
      transport?.terminate();
      transport?.removeListener('error', onPipeError);
      if (proc && !closed) {
        terminationStarted = performance.now();
        const closeStartedMs = observedMs();
        const tracked = {
          get exitCode() { return proc.exitCode; },
          get signalCode() { return proc.signalCode; },
          kill(name) {
            const key = name === 'SIGTERM' ? 'term' : 'kill';
            observed[`${key}Ms`] ??= observedMs();
            termination[key] = 'attempted';
            try {
              const accepted = signalChild(name);
              termination[key] = accepted ? 'accepted' : 'refused';
              return accepted;
            } catch (error) {
              termination.error = safeSignalError(error);
              termination[key] = 'threw';
              throw error;
            }
          },
        };
        if (!exited) escalation = killWithEscalation(tracked, {
          label: 'Composition browser', delayMs: Math.min(1000, shutdownMs / 2),
          stillRunning: () => !exited,
        });
        if (ownsProcessGroup) {
          observationTimer = setTimeout(() => {
            if (!closed) sampleGroup('deadline');
          }, Math.max(0, shutdownMs - observationBudgetMs));
          observationTimer.unref?.();
        }
        await Promise.race([childClosed, new Promise((_, reject) => {
          deadline = setTimeout(() => {
            closeDeadlineExpired = true;
            // Never interpolate arbitrary child properties, errors or output.
            // Public status and observed events are separate evidence: accepted
            // signals alone do not establish that the child has exited.
            const { exitCode, signalCode } = childStatus();
            const facts = {
              exit: exited, stdioClosed: Boolean(proc.stderr?.destroyed),
              term: termination.term, kill: termination.kill, signalError: termination.error,
              groupTerm: groupTermination.term, groupKill: groupTermination.kill, groupSignalError: groupTermination.error,
              groupFailedSignal: groupTermination.failedSignal, groupFailedPhase: groupTermination.failedPhase,
              groupSignalObservation: groupObservations.signal, groupDeadlineObservation: groupObservations.deadline,
              elapsedMs: Math.round(performance.now() - terminationStarted),
              spawned, closed, exitCode, signalCode,
              exitListener: proc.listeners('exit').includes(onExit),
              closeListener: proc.listeners('close').includes(onClose),
              errorListener: proc.listeners('error').includes(onError),
              ...observed, closeStartedMs, timeoutMs: observedMs(),
            };
            reject(new Error(`Composition browser cleanup exceeded its deadline (${Object.entries(facts).map(([key, value]) => `${key}=${value ?? 'unobserved'}`).join(', ')})`));
          }, shutdownMs);
        })]);
      }
    } finally {
      clearTimeout(escalation);
      clearTimeout(deadline);
      clearTimeout(observationTimer);
      // Wait for the process and our pipe to close before removing its profile.
      if (!proc || closed) {
        await cleanupProfile();
      }
    }
  })();
  const abort = () => { close().catch(() => {}); };
  try {
    signal?.throwIfAborted();
    const facts = piped ? (support || await readPreviewIsolationSupport()) : null;
    // Chrome cannot stack its process sandbox inside Seatbelt or bubblewrap:
    // sandbox_init fails with EPERM and the renderer, network, and GPU
    // processes crash. The outer jail is the egress boundary, so only those
    // launches pass --no-sandbox. Legacy renders keep Chrome's sandbox.
    const jailed = isolation === 'required' || isolation === 'os';
    const plan = piped ? previewIsolationPlan({
      ...facts, executable, profileDir: profile, dropSandbox: sandboxArgs().length > 0 || jailed, isolation,
    }) : null;
    if (piped && (isolation === 'required' || isolation === 'os') && !plan.supported) throw isolationUnavailable(plan.reason);
    const command = piped ? plan.command : executable;
    const args = piped ? plan.args : [
      '--headless=new', ...sandboxArgs(), '--remote-debugging-address=127.0.0.1', '--remote-debugging-port=0',
      `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check',
      '--mute-audio', '--disable-background-networking', '--disable-background-timer-throttling',
      '--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding', 'about:blank',
    ];
    proc = spawn(command, args, piped
      ? { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'], env: previewBrowserEnv(), detached: true }
      : safeChildProcessOptions({ stdio: ['ignore', 'ignore', 'pipe'], detached: ownsProcessGroup }));
    proc.once('spawn', () => { spawned = true; observed.spawnMs = observedMs(); });
    proc.once('exit', onExit);
    proc.once('close', onClose);
    proc.on('error', onError);
    observe('child', profile, { child: proc });
    if (piped) {
      transport = createCdpPipeTransport(proc);
      transport.on('error', onPipeError);
    }
    const ready = await new Promise((resolve, reject) => {
      let tail = '';
      const timer = setTimeout(() => finish(new Error('Composition browser startup exceeded its deadline')), startupMs);
      const finish = (error, value) => {
        rejectStartupPipe = null;
        clearTimeout(timer);
        proc.stderr?.removeListener('data', onData);
        transport?.removeListener('message', onHandshake);
        proc.removeListener('error', fail);
        proc.removeListener('exit', stopped);
        signal?.removeEventListener('abort', canceled);
        error ? reject(error) : resolve(value);
      };
      const fail = error => finish(new Error(`Composition browser failed to start (${error.code || 'spawn error'})`));
      const stopped = () => {
        const status = proc.signalCode ? `signal ${proc.signalCode}` : `code ${proc.exitCode ?? 'unknown'}`;
        const cause = ROOT_SANDBOX_REFUSAL.test(tail) ? ': Chrome refuses to run as root with its sandbox enabled' : '';
        finish(new Error(`Composition browser exited during startup (${status})${cause}`));
      };
      const canceled = () => finish(signal.reason ?? new Error('Render canceled'));
      const onData = bytes => {
        tail = (tail + bytes.toString()).slice(-8192);
        if (piped) return;
        // No paths or raw browser output are copied into errors. An endpoint must
        // be loopback and come from this child's complete DevTools line.
        const match = tail.match(/(?:^|\n)DevTools listening on (ws:\/\/127\.0\.0\.1:\d+\/devtools\/browser\/[a-zA-Z0-9-]+)\r?\n/);
        if (match) finish(null, match[1]);
      };
      const onHandshake = (bytes) => {
        let message;
        try { message = JSON.parse(bytes.toString()); } catch { return; }
        if (message.id !== 0) return;
        if (message.error) finish(new Error('Composition browser did not answer its startup handshake'));
        else finish(null, message.result || {});
      };
      proc.stderr?.on('data', onData);
      proc.once('error', fail);
      proc.once('exit', stopped);
      signal?.addEventListener('abort', canceled, { once: true });
      if (piped) {
        rejectStartupPipe = () => finish(new Error('Composition browser failed to start (pipe)'));
        transport.on('message', onHandshake);
        transport.send(JSON.stringify({ id: 0, method: 'Browser.getVersion' }), (error) => {
          if (error) finish(new Error('Composition browser failed to start (pipe)'));
        });
      }
      if (signal?.aborted) canceled();
      else if (exited) stopped();
    });
    // Drain subsequent diagnostics without retaining private output or letting
    // Chrome block on a full stderr pipe during a song-length capture.
    proc.stderr?.resume();
    signal?.addEventListener('abort', abort, { once: true });
    signal?.throwIfAborted();
    if (startupPipeError) throw new Error('Composition browser failed to start (pipe)');
    if (piped) return { transport, close, lifecycleFacts, mechanism: plan.mechanism };
    return { webSocketDebuggerUrl: ready, close, lifecycleFacts };
  } catch (error) {
    await close();
    throw error;
  }
}