@parall/daemon 1.36.1 → 1.37.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAgTA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAuD9E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAkTA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAuD9E"}

package/dist/cli.js

@@ -219,11 +219,11 @@ function cmdServiceUninstall() {
     }
 }
 async function cmdUpdate(checkOnly) {
-    const { resolveClaudeDaemonConfig, resolveBundleDir } = await import('./config.js');
+    const { resolveClaudeDaemonConfig, resolveBundleDir, resolveUpdateSigningEnabled } = await import('./config.js');
     const { DaemonUpdater } = await import('./updater.js');
     const config = resolveClaudeDaemonConfig(process.env);
     const bundleDir = resolveBundleDir(process.env);
-    const signingEnabled = process.env.PRLL_DAEMON_SIGNING_DISABLED !== '1';
+    const signingEnabled = resolveUpdateSigningEnabled(process.env);
     const updater = new DaemonUpdater(bundleDir, config.updateCdnUrl, {
         info: (msg) => console.log(msg),
         warn: (msg) => console.warn(msg),

package/dist/clip-runtime/browser-daemon-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Build the env for a spawned bb-browser daemon: inherit the parent env (so the
+ * Chromium it launches keeps PATH / HOME / DISPLAY / XDG / locale / proxy — the
+ * hosted browser-docker pod runs Chrome under Xvfb and depends on these), set
+ * BB_BROWSER_HOME, and strip the **platform credentials the daemon/pod carries**
+ * before they reach the child — bb-browser uses none of them and the Chromium it
+ * launches runs untrusted web content, so credentials must never land in its env:
+ *   - LLM/provider creds (`ANTHROPIC_*` / `OPENAI_*` / `PRLL_CLAUDE_ALLOW_API_KEY`,
+ *     via the maintained `clearAllProviderCreds` SSOT);
+ *   - the machine key (`PRLL_API_KEY=mck_`, BYOC control plane);
+ *   - hosted-pod creds injected by the browser-profile-controller (browser-pod.ts):
+ *     the platform assignment / pool tokens (`PRLL_ASSIGNMENT_TOKEN`,
+ *     `PRLL_POOL_TOKEN`, `pba_`) and the S3 browser-state STS creds (`AWS_*`).
+ * It also drops the hosted browser-state config the controller injects alongside
+ * those creds (`AWS_REGION`, `PRLL_BROWSER_STATE_BUCKET`, `PRLL_STATE_GENERATION`,
+ * `PRLL_BROWSER_STATE_ENDPOINT`): bb-browser never reads it, so dropping it shrinks
+ * the env surface handed to a process running untrusted content. (Unrelated BYOC
+ * host env is out of scope.)
+ *
+ * ts/daemon/AGENTS.md requires the credential env to be overridden before spawning
+ * a child, and with one bb-browser per profile the exposure would otherwise be
+ * multiplied N×. Denylist rather than allowlist: the SAME spawn feeds the Xvfb
+ * Chromium in the hosted pod, whose full env surface can't be exercised locally, so
+ * a too-narrow allowlist would silently break it — a denylist cannot. The hosted
+ * keys below are a safe no-op on a BYOC host (its env never carries them). Exported
+ * for unit testing.
+ */
+export declare function buildBrowserDaemonEnv(baseEnv: NodeJS.ProcessEnv, homeDir: string): NodeJS.ProcessEnv;
+//# sourceMappingURL=browser-daemon-env.d.ts.map

package/dist/clip-runtime/browser-daemon-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-daemon-env.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-daemon-env.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,UAAU,CAOnB"}

package/dist/clip-runtime/browser-daemon-env.js

@@ -0,0 +1,70 @@
+import { clearAllProviderCreds } from '@parall/agent-core';
+// Env sanitization for the spawned bb-browser daemon child (and the Chromium it
+// launches, which runs untrusted web content). Split out of browser-profile-manager
+// to keep that file under the size threshold; this is a distinct concern (env
+// scrubbing) from the daemon/account/tab lifecycle.
+/** Env vars stripped from the bb-browser child — the platform credentials it must
+ *  never carry, plus hosted browser-state config it doesn't use (in addition to the
+ *  provider creds scrubbed by clearAllProviderCreds). See buildBrowserDaemonEnv. */
+const BROWSER_DAEMON_STRIPPED_ENV = [
+    'PRLL_API_KEY', // machine key (mck_) — BYOC + agent control plane
+    'PRLL_PROVIDER_CONFIG', // JSON ProviderConfig blob — may carry BYO LLM api keys
+    'PRLL_ASSIGNMENT_TOKEN', // hosted pod platform assignment token (pba_)
+    'PRLL_POOL_TOKEN', // hosted warm-pool bootstrap token (pba_)
+    'AWS_ACCESS_KEY_ID', // hosted S3 browser-state STS creds (browser-pod.ts)
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    // AWS credential-RESOLUTION vars: the SDK derives creds from these too (IRSA
+    // web-identity, ECS/EKS container creds, named profile, on-disk cred/config
+    // files), so a child inheriting them could assume the pod's role even without
+    // the static keys above. bb-browser uses none of them.
+    'AWS_WEB_IDENTITY_TOKEN_FILE',
+    'AWS_ROLE_ARN',
+    'AWS_ROLE_SESSION_NAME',
+    'AWS_CONTAINER_CREDENTIALS_RELATIVE_URI',
+    'AWS_CONTAINER_CREDENTIALS_FULL_URI',
+    'AWS_CONTAINER_AUTHORIZATION_TOKEN',
+    'AWS_PROFILE',
+    'AWS_SHARED_CREDENTIALS_FILE',
+    'AWS_CONFIG_FILE',
+    'AWS_REGION', // hosted browser-state config — bb-browser does not use it
+    'PRLL_BROWSER_STATE_REGION', // browser-pod AWS_REGION fallback — same config family
+    'PRLL_BROWSER_STATE_BUCKET',
+    'PRLL_STATE_GENERATION',
+    'PRLL_BROWSER_STATE_ENDPOINT',
+];
+/**
+ * Build the env for a spawned bb-browser daemon: inherit the parent env (so the
+ * Chromium it launches keeps PATH / HOME / DISPLAY / XDG / locale / proxy — the
+ * hosted browser-docker pod runs Chrome under Xvfb and depends on these), set
+ * BB_BROWSER_HOME, and strip the **platform credentials the daemon/pod carries**
+ * before they reach the child — bb-browser uses none of them and the Chromium it
+ * launches runs untrusted web content, so credentials must never land in its env:
+ *   - LLM/provider creds (`ANTHROPIC_*` / `OPENAI_*` / `PRLL_CLAUDE_ALLOW_API_KEY`,
+ *     via the maintained `clearAllProviderCreds` SSOT);
+ *   - the machine key (`PRLL_API_KEY=mck_`, BYOC control plane);
+ *   - hosted-pod creds injected by the browser-profile-controller (browser-pod.ts):
+ *     the platform assignment / pool tokens (`PRLL_ASSIGNMENT_TOKEN`,
+ *     `PRLL_POOL_TOKEN`, `pba_`) and the S3 browser-state STS creds (`AWS_*`).
+ * It also drops the hosted browser-state config the controller injects alongside
+ * those creds (`AWS_REGION`, `PRLL_BROWSER_STATE_BUCKET`, `PRLL_STATE_GENERATION`,
+ * `PRLL_BROWSER_STATE_ENDPOINT`): bb-browser never reads it, so dropping it shrinks
+ * the env surface handed to a process running untrusted content. (Unrelated BYOC
+ * host env is out of scope.)
+ *
+ * ts/daemon/AGENTS.md requires the credential env to be overridden before spawning
+ * a child, and with one bb-browser per profile the exposure would otherwise be
+ * multiplied N×. Denylist rather than allowlist: the SAME spawn feeds the Xvfb
+ * Chromium in the hosted pod, whose full env surface can't be exercised locally, so
+ * a too-narrow allowlist would silently break it — a denylist cannot. The hosted
+ * keys below are a safe no-op on a BYOC host (its env never carries them). Exported
+ * for unit testing.
+ */
+export function buildBrowserDaemonEnv(baseEnv, homeDir) {
+    const env = { ...baseEnv, BB_BROWSER_HOME: homeDir };
+    clearAllProviderCreds(env); // strips ANTHROPIC_* / OPENAI_* / PRLL_CLAUDE_ALLOW_API_KEY
+    for (const key of BROWSER_DAEMON_STRIPPED_ENV) {
+        delete env[key];
+    }
+    return env;
+}

package/dist/clip-runtime/browser-profile-manager.d.ts

@@ -1,5 +1,5 @@
 import { type ViewerTurnConfig } from './browser-viewer-streamer.js';
-type BrowserProfileStatus = 'running' | 'stopped' | 'error';
+export type BrowserProfileStatus = 'running' | 'stopped' | 'error';
 /** Per-profile outbound proxy (BYO provider credentials) bound at bb-browser
  *  account_create. server is host:port (optional http/https/socks5 scheme);
  *  username/password authenticate (CDP Fetch.authRequired). Geo/session targeting
@@ -9,7 +9,7 @@ export interface BrowserProxyConfig {
     username?: string;
     password?: string;
 }
-interface BrowserProfileManagerOptions {
+export interface BrowserProfileManagerOptions {
     homeDir: string;
     log: {
         info(msg: string): void;
@@ -25,24 +25,37 @@ interface BrowserProfileManagerOptions {
      *  IP for a proxy-configured profile). */
     resolveProxy?: (profileId: string) => Promise<BrowserProxyConfig | null> | BrowserProxyConfig | null;
 }
-interface BrowserInvokeRequest {
+export interface BrowserInvokeRequest {
     profileId: string;
     account: string;
     command: string;
     input: unknown;
 }
+/**
+ * The host-side browser invoke surface ClipProcessManager depends on. Both
+ * BrowserProfileManager (one bb-browser, multi-account — used by the hosted
+ * browser pod) and BrowserProfilePool (one bb-browser per profile — used by the
+ * BYOC daemon supervisor for true per-profile isolation) satisfy it, so the
+ * synthetic "browser" capability routes through either without caring which.
+ */
+export interface BrowserInvoker {
+    invoke(request: BrowserInvokeRequest): Promise<unknown>;
+}
 export declare class BrowserProfileManager {
     private readonly opts;
     private daemon;
     private starting;
     private restarting;
+    private stopping;
     private readonly ensuredAccounts;
     private readonly ensuringAccounts;
     private readonly reportedStatuses;
     private readonly viewer;
     constructor(opts: BrowserProfileManagerOptions);
     invoke({ profileId, account, command, input }: BrowserInvokeRequest): Promise<unknown>;
-    ensureRuntime(profileId: string): Promise<void>;
+    ensureRuntime(profileId: string, opts?: {
+        forceStatusReport?: boolean;
+    }): Promise<void>;
     openProfile(profileId: string, startUrl?: string): Promise<void>;
     stopProfile(profileId: string): Promise<void>;
     resetProfile(profileId: string): Promise<void>;
@@ -90,7 +103,7 @@ export declare class BrowserProfileManager {
     private restartDaemon;
     private restartDaemonOnce;
     private startDaemon;
+    private startDaemonAttempt;
     private post;
 }
-export {};
 //# sourceMappingURL=browser-profile-manager.d.ts.map

package/dist/clip-runtime/browser-profile-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-profile-manager.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-profile-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-profile-manager.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-profile-manager.ts"],"names":[],"mappings":"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"}

package/dist/clip-runtime/browser-profile-manager.js

@@ -4,9 +4,13 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { buildBrowserDaemonEnv } from './browser-daemon-env.js';
 import { BrowserViewerStreamer } from './browser-viewer-streamer.js';
-import { findFreePort, formatErrorForLog, sleep } from './subprocess.js';
+import { findFreePort, formatErrorForLog, sleep, waitForChildExit } from './subprocess.js';
 const BB_BROWSER_DAEMON_START_TIMEOUT_MS = 15_000;
+// Retries for a transient port collision when several daemons boot in parallel
+// (probe-and-close port allocation is TOCTOU); each retry re-rolls fresh ports.
+const BB_BROWSER_DAEMON_START_ATTEMPTS = 3;
 class BrowserCommandError extends Error {
     method;
     account;
@@ -22,6 +26,11 @@ export class BrowserProfileManager {
     daemon = null;
     starting = null;
     restarting = null;
+    // Set by stop() and never reset (stop() is terminal — the pool disposes the
+    // manager and the hosted pod exits). Makes a startDaemon() that resolves after
+    // stop() began un-adoptable, so a late child can't be reassigned to this.daemon
+    // and escape teardown.
+    stopping = false;
     ensuredAccounts = new Set();
     ensuringAccounts = new Map();
     reportedStatuses = new Map();
@@ -77,9 +86,19 @@ export class BrowserProfileManager {
             throw err;
         }
     }
-    async ensureRuntime(profileId) {
+    async ensureRuntime(profileId, opts = {}) {
         if (!profileId)
             throw new Error('browser profile id is required');
+        // forceStatusReport is set by the reconnect reconcile for a `pending` row: the server
+        // flipped the row to `pending` (an `open` API call) while the daemon was disconnected
+        // but its Chromium stayed alive, so our last report was already `running`. A deduped
+        // repeat would be swallowed and leave the server stuck at `pending` — clear the marker
+        // (as openProfile / stopProfile do) so this recovery report is authoritative for both
+        // `running` and `error`. A plain (non-forced) ensure keeps the dedup so a `running`
+        // row's chatty re-confirmations are still suppressed.
+        if (opts.forceStatusReport) {
+            this.reportedStatuses.delete(profileId);
+        }
         try {
             await this.withDaemonRecovery(() => this.ensureAccount(profileId), `ensure runtime for ${profileId}`);
             this.reportStatus(profileId, 'running');
@@ -140,25 +159,61 @@ export class BrowserProfileManager {
         }
     }
     async stop() {
+        this.stopping = true;
         // Tear down all per-profile bb-viewer streamers before the bb-browser daemon.
         this.viewer.shutdown();
+        // Capture an IN-FLIGHT startup too: a startDaemon() resolving after we snapshot
+        // this.daemon would otherwise produce a fresh child this stop never kills. The
+        // ensureDaemon stopping-guard refuses to ADOPT it (won't set this.daemon), but
+        // only we can shut it down — so await the startup here and tear down whatever it
+        // produced. `daemon` and `starting` are mutually exclusive (ensureDaemon sets
+        // this.daemon then nulls this.starting in finally), so at most one is set.
+        const inflight = this.starting;
+        // An in-flight restartDaemonOnce() has already cleared this.daemon/this.starting
+        // and is awaiting the PREVIOUS child's waitForChildExit. Join it so stop() does
+        // not return — letting the hosted pod's drain checkpoint run — before that child
+        // (and its Chromium) has actually exited and flushed state. The stopping guard
+        // set above prevents its post-restart retry from spawning a fresh daemon.
+        const restarting = this.restarting;
         const daemon = this.daemon;
         this.daemon = null;
         this.starting = null;
         this.ensuredAccounts.clear();
         this.ensuringAccounts.clear();
         this.reportedStatuses.clear();
-        if (!daemon)
-            return;
-        try {
-            await this.post('/shutdown', daemon, undefined, 3_000);
-        }
-        catch {
-            /* best-effort */
+        if (restarting) {
+            try {
+                await restarting;
+            }
+            catch {
+                /* restart failure is already logged by restartDaemonOnce */
+            }
         }
-        if (daemon.child.exitCode === null && daemon.child.signalCode === null) {
-            daemon.child.kill('SIGTERM');
+        let started = null;
+        if (inflight) {
+            try {
+                started = await inflight;
+            }
+            catch {
+                /* startup failed — nothing to tear down */
+            }
         }
+        // Wait for each child (and its Chromium) to ACTUALLY exit before returning: the
+        // same per-profile home is reused right after — the pool reopens/resets it, or a
+        // recovery restart spawns a new daemon on it — so returning while Chromium is
+        // still tearing down would race a new Chromium / a state wipe on the same
+        // user-data-dir.
+        await Promise.all([daemon, started]
+            .filter((d) => d !== null)
+            .map(async (d) => {
+            try {
+                await this.post('/shutdown', d, undefined, 3_000);
+            }
+            catch {
+                /* best-effort */
+            }
+            await waitForChildExit(d.child, this.opts.log);
+        }));
     }
     /**
      * Viewer control command entrypoint — delegates to BrowserViewerStreamer
@@ -408,20 +463,39 @@ export class BrowserProfileManager {
     async ensureDaemon() {
         if (this.restarting)
             await this.restarting;
+        if (this.stopping)
+            throw new Error('browser profile manager is stopping');
         if (this.daemon &&
             this.daemon.child.exitCode === null &&
             this.daemon.child.signalCode === null) {
             return this.daemon;
         }
-        if (this.starting)
-            return this.starting;
+        if (this.starting) {
+            // A concurrent caller shares the in-flight start, but must re-check the stopping
+            // guard after awaiting it — exactly like the owner below. Otherwise stop() beginning
+            // mid-start would hand this waiter the freshly-started daemon that stop() is tearing
+            // down, and it would post a command into teardown (the resurrect race, via the
+            // waiter path). Fail closed instead.
+            const started = await this.starting;
+            if (this.stopping)
+                throw new Error('browser profile manager is stopping');
+            return started;
+        }
         this.starting = this.startDaemon();
+        const startPromise = this.starting;
         try {
-            this.daemon = await this.starting;
+            const started = await startPromise;
+            // stop() may have begun while we were starting; it captured this same promise
+            // and tears the child down. Do NOT adopt it as this.daemon, or it would escape
+            // teardown — exactly the resurrect race this guard closes.
+            if (this.stopping)
+                throw new Error('browser profile manager is stopping');
+            this.daemon = started;
             return this.daemon;
         }
         finally {
-            this.starting = null;
+            if (this.starting === startPromise)
+                this.starting = null;
         }
     }
     async withDaemonRecovery(operation, label) {
@@ -461,20 +535,67 @@ export class BrowserProfileManager {
         catch {
             /* best-effort */
         }
-        if (daemon.child.exitCode === null && daemon.child.signalCode === null) {
-            daemon.child.kill('SIGTERM');
-        }
+        // Wait for the bb-browser child (and its Chromium) to ACTUALLY exit before
+        // returning: the same per-profile home is reused right after — the pool
+        // reopens/resets it, or a recovery restart spawns a new daemon on it — so
+        // returning while Chromium is still tearing down would race a new Chromium /
+        // a state wipe against the old one on the same user-data-dir.
+        await waitForChildExit(daemon.child, this.opts.log);
     }
     async startDaemon() {
+        // findFreePort() probes by binding :0 then closing, so when the supervisor
+        // boots several profiles' bb-browser daemons in parallel two can grab the same
+        // just-freed port and the loser's Chromium fails to bind. Retry with fresh
+        // ports so a transient collision self-heals instead of stranding the profile
+        // until the next reconcile. A port-collision attempt fails fast (the child
+        // exits on EADDRINUSE), so the retries don't stack the full start timeout.
+        let lastErr;
+        for (let attempt = 1; attempt <= BB_BROWSER_DAEMON_START_ATTEMPTS; attempt++) {
+            try {
+                return await this.startDaemonAttempt();
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt < BB_BROWSER_DAEMON_START_ATTEMPTS) {
+                    this.opts.log.warn(`[bb-browser] daemon start attempt ${attempt} failed; retrying with fresh ports: ${String(err)}`);
+                }
+            }
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    async startDaemonAttempt() {
         const host = '127.0.0.1';
         const port = await findFreePort();
+        // Each bb-browser daemon launches its OWN Chromium. bb-browser defaults the
+        // CDP port to 9222, so running more than one daemon per host (the BYOC
+        // supervisor's BrowserProfilePool spawns one bb-browser per profile for
+        // hard isolation) would collide on 9222 → only the first profile's Chrome
+        // starts. Bind a free CDP port per daemon; every consumer reads the live
+        // port from GET /status (cdpEndpoint), so nothing depends on 9222.
+        // findFreePort() probes by binding :0 then closing, so two back-to-back calls
+        // can hand back the SAME ephemeral port — the HTTP and CDP ports must differ,
+        // so re-roll the CDP port if it collides with the HTTP port.
+        let cdpPort = await findFreePort();
+        for (let i = 0; cdpPort === port && i < 5; i++) {
+            cdpPort = await findFreePort();
+        }
+        if (cdpPort === port) {
+            throw new Error('bb-browser: could not allocate distinct HTTP and CDP ports');
+        }
         const token = randomToken();
         const daemonPath = resolveBbBrowserDaemonPath();
-        const child = spawn(process.execPath, [daemonPath, '--host', host, '--port', String(port), '--token', token], {
-            env: {
-                ...process.env,
-                BB_BROWSER_HOME: this.opts.homeDir,
-            },
+        const child = spawn(process.execPath, [
+            daemonPath,
+            '--host',
+            host,
+            '--port',
+            String(port),
+            '--token',
+            token,
+            '--cdp-port',
+            String(cdpPort),
+        ], {
+            env: buildBrowserDaemonEnv(process.env, this.opts.homeDir),
             stdio: ['ignore', 'ignore', 'pipe'],
         });
         // A spawn/exec failure (ENOENT, EACCES, …) emits 'error' on the child, which
@@ -507,7 +628,11 @@ export class BrowserProfileManager {
                 await sleep(200);
             }
         }
-        child.kill('SIGTERM');
+        // Await the timed-out child's exit before failing: a retry reuses the SAME
+        // per-profile home, so returning while this Chromium is still shutting down
+        // would race the next startup against it on the same user-data-dir (same
+        // guarantee as stop/restart). waitForChildExit sends SIGTERM, then SIGKILL.
+        await waitForChildExit(child, this.opts.log);
         throw new Error('bb-browser-daemon did not start in time');
     }
     async post(pathName, daemon, body, timeoutMs = 10_000) {