@parall/daemon 1.35.0 → 1.36.0

package/dist/clip-runtime/browser-viewer-streamer.js

@@ -11,12 +11,40 @@ const BB_VIEWER_COMMAND_TIMEOUT_MS = 15_000;
 const BB_VIEWER_UNANSWERED_REAP_MS = 90_000;
 // Grace between SIGTERM and the SIGKILL escalation in killChild.
 const BB_VIEWER_TERM_GRACE_MS = 5_000;
+/**
+ * bb-viewer's /command control plane is UNAUTHENTICATED, so on the shared agents
+ * cluster its bind host MUST be loopback — a 0.0.0.0 / pod-IP / typo'd value would
+ * silently re-open it cross-tenant. Only these exact loopback forms are accepted;
+ * anything else is rejected (fail fast) at spawn.
+ */
+export function isLoopbackBindHost(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]';
+}
+/**
+ * Whether a kick targets the CURRENT live streamer (so its process is torn down). A
+ * kick with no explicit target hits whoever is live; an explicit target tears down the
+ * current streamer ONLY when it matches — a stale/replayed session_id must not kill a
+ * newer live viewer (it is only recorded for straggler rejection). currentSessionId
+ * undefined (no live streamer) → never a current-kill.
+ */
+export function kickHitsCurrentSession(requested, currentSessionId) {
+    if (currentSessionId === undefined)
+        return false;
+    return requested === undefined || requested === currentSessionId;
+}
 export class BrowserViewerStreamer {
     host;
     // Live bb-viewer (WebRTC streamer) subprocess per profile. One per profile;
     // see StreamerState. Cleaned up on stream.close, stopProfile, resetProfile,
     // and stop().
     streamers = new Map();
+    // The most-recently server-side-kicked viewer session per profile (design §3.6
+    // PR7). After a kick the streamer is gone, so the session-staleness guards
+    // (which key off a live streamer) can no longer reject the kicked viewer's
+    // straggler nav commands — this map does. Reset whenever the profile's streamer
+    // is (re)killed via killProfileStreamer, so a fresh stream.start clears it. One
+    // entry per profile (overwritten per kick); bounded, no leak.
+    kickedSessions = new Map();
     // Set by shutdown(): an in-flight spawnStreamer has no map entry yet, so a
     // shutdown during its health poll would otherwise let the bb-viewer child
     // survive daemon stop (on BYOC nothing else reaps it).
@@ -33,6 +61,16 @@ export class BrowserViewerStreamer {
     async handleViewerCommand(profileId, sessionId, command, input, turn) {
         if (!profileId)
             throw new Error('browser profile id is required');
+        // Reject a kicked viewer's straggler commands (design §3.6 PR7). After a kick
+        // there is no streamer, so the per-command staleness guards (which compare
+        // against a live streamer's sessionId) would let a kicked viewer keep driving
+        // nav. A fresh stream.start re-establishes a session (killProfileStreamer
+        // clears the marker), so it is exempt.
+        if (command !== 'stream.start' &&
+            sessionId &&
+            this.kickedSessions.get(profileId) === sessionId) {
+            throw new Error('viewer session was terminated');
+        }
         switch (command) {
             case 'stream.start':
                 return this.viewerStreamStart(profileId, sessionId, turn);
@@ -42,6 +80,8 @@ export class BrowserViewerStreamer {
                 return this.viewerStreamClose(profileId, sessionId, input);
             case 'stream.switch':
                 return this.viewerStreamSwitch(profileId, sessionId, input);
+            case 'kick':
+                return this.viewerKick(profileId, sessionId, input);
             case 'close':
                 return this.viewerCloseTab(profileId, sessionId, input);
             case 'tab_list':
@@ -55,6 +95,36 @@ export class BrowserViewerStreamer {
                 throw new Error(`unknown viewer command: ${command}`);
         }
     }
+    /**
+     * kick — server-side per-viewer disconnect (design §3.6 PR7). Terminates ONE
+     * viewer's WebRTC session: stop its bb-viewer streamer (killing the process
+     * tears down the peer connection + datachannel) and reject the kicked session's
+     * subsequent commands — while bb-browser + Chromium (the agent's live browser)
+     * keep running. This is explicitly DISTINCT from stopping the pod / profile,
+     * which would kill the agent's browser too; a viewer session is a sub-session of
+     * the profile lease, so a kick does NOT release the lease.
+     *
+     * Targets `input.session_id` if given, else the current streamer's session.
+     * Idempotent: kicking with no live streamer still records the kicked session.
+     */
+    viewerKick(profileId, sessionId, input) {
+        const streamer = this.streamers.get(profileId);
+        const requested = typeof input?.session_id === 'string' ? input.session_id : undefined;
+        const target = requested || streamer?.sessionId || sessionId;
+        // Only tear down the LIVE streamer when the kick targets the current session — a
+        // replayed/delayed stale session_id must not kill a newer live viewer. A kick with
+        // no explicit target (kick "whoever is live") also tears it down. A stale target is
+        // still recorded so its straggler commands are rejected by the staleness guard.
+        const killsCurrent = kickHitsCurrentSession(requested, streamer?.sessionId);
+        if (killsCurrent) {
+            // killProfileStreamer clears the kick marker, so record the target AFTER it.
+            this.killProfileStreamer(profileId);
+        }
+        if (target)
+            this.kickedSessions.set(profileId, target);
+        this.host.log.info(`[bb-viewer] kicked viewer session ${target || '(none)'} for profile ${profileId}; pod + agent browser keep running`);
+        return target ? { ok: true, kicked: true, session_id: target } : { ok: true, kicked: true };
+    }
     /**
      * stream.start — spawn a FRESH bb-viewer for this profile (killing any prior
      * one), resolve the profile's account-scoped page-target CDP ws URL, and run
@@ -394,6 +464,26 @@ export class BrowserViewerStreamer {
         const bin = process.env.PRLL_BB_VIEWER_BIN ?? 'bb-viewer';
         const port = await findFreePort();
         const args = ['--api-only', '--port', String(port)];
+        // Bind bb-viewer's HTTP control surface (/command + /health) to a specific
+        // host when the image opts in via PRLL_BB_VIEWER_HOST (the hosted browser pod
+        // sets it to 127.0.0.1; design §3.6 PR7). The streamer ALWAYS reaches
+        // bb-viewer over loopback (streamerCommand + the health poll below both use
+        // 127.0.0.1), so a loopback bind never breaks the in-pod path — it only
+        // removes the 0.0.0.0 exposure that, on the shared agents cluster, would let
+        // another tenant's pod re-point this streamer or start its own stream. Left
+        // unset (no --host) for BYOC and the current pinned bb-viewer, which has no
+        // --host flag — see deploy/browser-docker/AGENTS.md "bb-viewer loopback bind".
+        const bindHost = process.env.PRLL_BB_VIEWER_HOST?.trim();
+        if (bindHost) {
+            // SECURITY: bb-viewer's /command is unauthenticated, so on the shared agents
+            // cluster its bind host MUST be loopback — a 0.0.0.0 / pod-IP / typo'd value would
+            // silently re-open the cross-tenant control plane this env exists to close. Fail
+            // fast on anything non-loopback rather than pass it through to --host.
+            if (!isLoopbackBindHost(bindHost)) {
+                throw new Error(`PRLL_BB_VIEWER_HOST must be loopback (127.0.0.1, localhost, ::1, [::1]) — refusing to bind bb-viewer's unauthenticated /command to ${bindHost}`);
+            }
+            args.push('--host', bindHost);
+        }
         if (turn?.url) {
             args.push('--turn-url', turn.url, '--turn-user', turn.username ?? '', '--turn-cred', turn.credential ?? '');
         }
@@ -528,8 +618,14 @@ export class BrowserViewerStreamer {
             clearTimeout(timer);
         }
     }
-    /** Kill + remove the profile's bb-viewer streamer, if any. Idempotent. */
+    /**
+     * Kill + remove the profile's bb-viewer streamer, if any. Idempotent. Also
+     * clears any kick marker for the profile: a (re)kill establishes a clean
+     * streamer slot, so a subsequent stream.start starts un-kicked. viewerKick
+     * re-records the kicked session AFTER calling this.
+     */
     killProfileStreamer(profileId) {
+        this.kickedSessions.delete(profileId);
         const streamer = this.streamers.get(profileId);
         if (!streamer)
             return;

package/dist/clip-runtime/clip-provider.d.ts

@@ -39,6 +39,26 @@ export interface ClipProviderOptions {
      * re-trigger machine.hello. Optional.
      */
     onPersistentFailure?: () => void;
+    /**
+     * Hosted-browser live-viewer handler. Set ONLY for a hosted browser pod
+     * (browser-pod.ts): clip-service relays viewer commands down the
+     * ProviderStream and the pod replies over it (design §3.4). Returns the
+     * streamer result on success; throws to signal a command-level error (its
+     * message is forwarded to the viewer). Absent for ordinary BYOC providers,
+     * which never receive ViewerCommands. Callers should serialize their own
+     * streamer state if needed — the provider invokes this per inbound command.
+     */
+    onViewerCommand?: (cmd: {
+        profileId: string;
+        sessionId: string;
+        command: string;
+        input?: Record<string, unknown>;
+        turn?: {
+            url: string;
+            username?: string;
+            credential?: string;
+        };
+    }) => Promise<Record<string, unknown>>;
 }
 export declare class ClipProvider {
     private readonly opts;
@@ -52,6 +72,7 @@ export declare class ClipProvider {
     private statusUnsubscribe;
     private manifestUnsubscribe;
     private needsReregister;
+    private lastRegisteredKey;
     private streamGeneration;
     private static RECONNECT_BASE_MS;
     private static RECONNECT_MAX_MS;
@@ -69,6 +90,31 @@ export declare class ClipProvider {
     private clearReconnectTimer;
     private clearHeartbeatTimer;
     private startHeartbeat;
+    /**
+     * Re-register the current clip set on the OPEN stream — the daemon's response
+     * to a manifest/clip-set change. The hub overwrites its stored set from this
+     * full register (clip-provider-sharing-design §11), so a clip install / wake /
+     * sleep no longer requires tearing down and reopening the ProviderStream,
+     * which used to drop any invoke in flight on that stream (in-flight requests
+     * are keyed by request_id on the hub and survive a clip-set swap).
+     *
+     * No-op when the stream is not currently writable; needsReregister stays set
+     * so the next heartbeat tick (or the post-connect flush) retries.
+     *
+     * Against an older hub that still rejects an in-stream duplicate register, the
+     * write reaches a stream the hub then resets; the resulting stream error runs
+     * the normal reconnect path, which re-registers as the first frame — i.e. it
+     * degrades to the previous reconnect-to-re-register behavior, so no capability
+     * negotiation is needed (deploy the hub first).
+     */
+    private flushReregister;
+    /**
+     * Re-register the current clip set on the open stream — public entry for the
+     * supervisor when machine clip assignments change. Same in-stream path as a
+     * manifest update (no reconnect, in-flight invokes survive). Safe when
+     * disconnected: the flag is flushed on the next heartbeat / post-connect.
+     */
+    reregister(): void;
     private closeStream;
     private closeSession;
     private subscribeStatusChanges;
@@ -76,6 +122,16 @@ export declare class ClipProvider {
     private handleHubMessage;
     private handleRegistered;
     private handleInvokeCommand;
+    /**
+     * Handle a hosted-browser live-viewer command relayed by clip-service over the
+     * stream and reply on the same stream (design §3.4). Always answers the
+     * request/reply bridge exactly once — `{result}` on success, `{error:{message}}`
+     * on failure — and never throws into the message loop, mirroring the BYOC
+     * daemon's handleBrowserProfileViewer (which replies over HTTP instead).
+     */
+    private handleViewerCommand;
+    /** Send a hosted-viewer reply (base64-encoded JSON body) on the stream. */
+    private sendViewerReply;
     private sendRegister;
     private sendProviderMessage;
     private buildClipRegistrations;

package/dist/clip-runtime/clip-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clip-provider.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/clip-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA+I/D,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,WAAW,EAAE,kBAAkB,CAAC;IAChC,mBAAmB;IACnB,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpF;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,qBAAa,YAAY;IAwBX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAvBjC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,eAAe,CAAS;IAIhC,OAAO,CAAC,gBAAgB,CAAK;IAE7B,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAS;IACzC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAU;IACzC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAU;IAI9C,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAK;gBAEjB,IAAI,EAAE,mBAAmB;IAEtD,mFAAmF;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,wCAAwC;IAClC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC,WAAW,IAAI,OAAO;YAQR,UAAU;IAuExB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,sBAAsB;IAyB9B,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,gBAAgB;YAeV,mBAAmB;YA0EnB,YAAY;YAUZ,mBAAmB;IAiBjC,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,cAAc;CAUvB"}
+{"version":3,"file":"clip-provider.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/clip-provider.ts"],"names":[],"mappings":"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"}

package/dist/clip-runtime/clip-provider.js

@@ -28,6 +28,17 @@ function encodeEnvelope(msg) {
     header.writeUInt32BE(json.length, 1);
     return Buffer.concat([header, json]);
 }
+/**
+ * Canonical key for a clip-registration set — used by flushReregister to skip a
+ * re-register that would not change the hub's view. Sorted by alias so set
+ * order is irrelevant; each registration's shape is fixed by
+ * clipConfigToRegistration, so its JSON is a stable digest of the hub-facing
+ * content (commands, version, dependencies, …).
+ */
+function registrationKey(clips) {
+    const sorted = [...clips].sort((a, b) => (a.alias ?? '').localeCompare(b.alias ?? ''));
+    return JSON.stringify(sorted);
+}
 /**
  * Incremental envelope decoder. Feed chunks via push(), receive decoded
  * messages from flush(). Handles partial reads across chunk boundaries.
@@ -66,7 +77,15 @@ export class ClipProvider {
     heartbeatTimer = null;
     statusUnsubscribe = null;
     manifestUnsubscribe = null;
+    // Set when the clip manifest/set changed and the hub's copy is stale. Drained
+    // by flushReregister(), which re-registers IN-STREAM (no reconnect).
     needsReregister = false;
+    // Canonical key of the clip-registration set last sent to the hub on the
+    // CURRENT stream. flushReregister diff-gates against it so a cold-start that
+    // re-derives an identical set (the common case — a clip's command surface is
+    // stable across spawns) does not emit a redundant re-register. Reset per
+    // stream; the first-frame register in openStream re-seeds it.
+    lastRegisteredKey = null;
     // Monotonic stream id, bumped by openStream(). Handlers from a stream that a
     // newer openStream() has superseded bail in handleDisconnect(gen), so their
     // late close/end/error can't reconnect against the healthy replacement.
@@ -109,6 +128,9 @@ export class ClipProvider {
             return;
         // Bind this stream's handlers to a fresh generation; older streams go stale.
         const gen = ++this.streamGeneration;
+        // New stream → the hub holds nothing until the first-frame register below
+        // re-seeds this; clear so a stale key can't suppress that register.
+        this.lastRegisteredKey = null;
         try {
             this.closeStream();
             this.closeSession();
@@ -218,25 +240,68 @@ export class ClipProvider {
     startHeartbeat() {
         this.clearHeartbeatTimer();
         this.heartbeatTimer = setInterval(() => {
-            // If a clip manifest was populated since last heartbeat, reconnect to
-            // re-register all clips with their now-available commands.
-            if (this.needsReregister) {
-                this.needsReregister = false;
-                this.opts.log.info('[clip-provider] manifest updated — reconnecting to re-register clips');
-                this.connected = false;
-                this.clearHeartbeatTimer();
-                this.clearReconnectTimer();
-                // openStream() bumps the generation before closing the old stream, so its
-                // late close events fail the gen check (closing inline would re-arm the flap).
-                void this.openStream();
-                return;
-            }
+            // A pending manifest/clip-set change re-registers IN-STREAM (no
+            // reconnect), so in-flight invokes on this stream survive. This is the
+            // fallback for when the immediate flush on the change itself could not
+            // write (e.g. it fired mid-(re)connect); the common case re-registers the
+            // instant the manifest changes via the manifest listener.
+            this.flushReregister();
             this.sendProviderMessage({ ping: { sentAtUnixMs: Date.now() } }).catch((err) => {
                 this.opts.log.warn(`[clip-provider] heartbeat send failed: ${String(err)}`);
             });
         }, ClipProvider.HEARTBEAT_INTERVAL_MS);
         this.heartbeatTimer.unref?.();
     }
+    /**
+     * Re-register the current clip set on the OPEN stream — the daemon's response
+     * to a manifest/clip-set change. The hub overwrites its stored set from this
+     * full register (clip-provider-sharing-design §11), so a clip install / wake /
+     * sleep no longer requires tearing down and reopening the ProviderStream,
+     * which used to drop any invoke in flight on that stream (in-flight requests
+     * are keyed by request_id on the hub and survive a clip-set swap).
+     *
+     * No-op when the stream is not currently writable; needsReregister stays set
+     * so the next heartbeat tick (or the post-connect flush) retries.
+     *
+     * Against an older hub that still rejects an in-stream duplicate register, the
+     * write reaches a stream the hub then resets; the resulting stream error runs
+     * the normal reconnect path, which re-registers as the first frame — i.e. it
+     * degrades to the previous reconnect-to-re-register behavior, so no capability
+     * negotiation is needed (deploy the hub first).
+     */
+    flushReregister() {
+        if (!this.needsReregister)
+            return;
+        if (!this.connected || !this.stream || this.stream.closed || this.stream.destroyed)
+            return;
+        // Diff-gate: a cold-start re-derives the clip set on every wake, but the
+        // hub-facing registration is usually identical (a clip's command surface is
+        // stable across spawns). Skip the redundant re-register so the hot path
+        // (invoke → wake clip → manifest re-read) does no hub work when nothing
+        // actually changed. Compare the canonical registration set against what this
+        // stream last sent.
+        const clips = this.buildClipRegistrations();
+        if (registrationKey(clips) === this.lastRegisteredKey) {
+            this.needsReregister = false;
+            return;
+        }
+        this.needsReregister = false;
+        this.opts.log.info('[clip-provider] re-registering clips in-stream');
+        this.sendRegister(clips).catch((err) => {
+            this.opts.log.warn(`[clip-provider] in-stream re-register failed: ${String(err)}`);
+            this.needsReregister = true; // retry on the next heartbeat tick
+        });
+    }
+    /**
+     * Re-register the current clip set on the open stream — public entry for the
+     * supervisor when machine clip assignments change. Same in-stream path as a
+     * manifest update (no reconnect, in-flight invokes survive). Safe when
+     * disconnected: the flag is flushed on the next heartbeat / post-connect.
+     */
+    reregister() {
+        this.needsReregister = true;
+        this.flushReregister();
+    }
     closeStream() {
         if (this.stream) {
             try {
@@ -279,9 +344,11 @@ export class ClipProvider {
                 this.opts.log.warn(`[clip-provider] status change send failed: ${String(err)}`);
             });
         });
-        // Listen for manifest updates so we can re-register with populated commands
+        // Listen for manifest updates so we can re-register with populated commands.
+        // Re-register immediately on the open stream; the heartbeat retries if the
+        // stream is momentarily not writable.
         this.manifestUnsubscribe = mgr.addManifestListener(() => {
-            this.needsReregister = true;
+            this.reregister();
         });
     }
     unsubscribeStatusChanges() {
@@ -300,6 +367,9 @@ export class ClipProvider {
         else if (msg.invokeCommand) {
             void this.handleInvokeCommand(msg.invokeCommand);
         }
+        else if (msg.viewerCommand) {
+            void this.handleViewerCommand(msg.viewerCommand);
+        }
         else if (msg.pong !== undefined) {
             // Pong is the hub's keepalive ack. Do NOT echo a ping here — the
             // heartbeat timer (startHeartbeat) is the sole ping driver. Replying to
@@ -313,6 +383,9 @@ export class ClipProvider {
             this.connected = true;
             this.reconnectAttempt = 0;
             this.startHeartbeat();
+            // A manifest change that landed during the connect handshake (after the
+            // initial register was sent) is flushed now that the stream is writable.
+            this.flushReregister();
         }
         else {
             this.opts.log.error(`[clip-provider] registration rejected: ${reg.message}`);
@@ -387,17 +460,68 @@ export class ClipProvider {
             }).catch(() => { }); // best-effort error response
         }
     }
+    /**
+     * Handle a hosted-browser live-viewer command relayed by clip-service over the
+     * stream and reply on the same stream (design §3.4). Always answers the
+     * request/reply bridge exactly once — `{result}` on success, `{error:{message}}`
+     * on failure — and never throws into the message loop, mirroring the BYOC
+     * daemon's handleBrowserProfileViewer (which replies over HTTP instead).
+     */
+    async handleViewerCommand(cmd) {
+        const { requestId } = cmd;
+        if (!this.opts.onViewerCommand) {
+            // A provider with no live-viewer handler received a viewer command (should
+            // not happen — only hosted pods are sent these). Fail the bridge fast.
+            await this.sendViewerReply(requestId, {
+                error: { message: 'live viewer is not supported by this provider' },
+            }).catch(() => { });
+            return;
+        }
+        try {
+            let input;
+            if (cmd.input) {
+                const decoded = Buffer.from(cmd.input, 'base64').toString('utf-8');
+                try {
+                    input = JSON.parse(decoded);
+                }
+                catch {
+                    input = undefined;
+                }
+            }
+            const result = await this.opts.onViewerCommand({
+                profileId: cmd.profileId,
+                sessionId: cmd.sessionId,
+                command: cmd.command,
+                input,
+                turn: cmd.turn,
+            });
+            await this.sendViewerReply(requestId, { result });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.opts.log.warn(`[clip-provider] viewer command failed (profile=${cmd.profileId}, command=${cmd.command}): ${message}`);
+            await this.sendViewerReply(requestId, { error: { message } }).catch(() => { });
+        }
+    }
+    /** Send a hosted-viewer reply (base64-encoded JSON body) on the stream. */
+    async sendViewerReply(requestId, reply) {
+        const payload = Buffer.from(JSON.stringify(reply), 'utf-8').toString('base64');
+        await this.sendProviderMessage({ viewerResult: { requestId, payload } });
+    }
     // ---------------------------------------------------------------------------
     // Sending
     // ---------------------------------------------------------------------------
-    async sendRegister() {
-        const clips = this.buildClipRegistrations();
+    async sendRegister(prebuilt) {
+        const clips = prebuilt ?? this.buildClipRegistrations();
         await this.sendProviderMessage({
             register: {
                 providerName: this.opts.providerName,
                 clips,
             },
         });
+        // Record what the hub now holds on this stream so flushReregister can
+        // diff-gate subsequent cold-start re-registers.
+        this.lastRegisteredKey = registrationKey(clips);
     }
     async sendProviderMessage(msg) {
         if (!this.stream || this.stream.closed || this.stream.destroyed) {

package/dist/supervisor.d.ts

@@ -89,7 +89,6 @@ export declare class DaemonSupervisor {
     private clipConfigSignature;
     private ensureClipInstalled;
     private readInstalledClipVersion;
-    private reconnectClipProvider;
     private handleWorkspaceSetupRequested;
     private scheduleWorkspaceSetupRetry;
     private clearWorkspaceSetupRetry;

package/dist/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAeL,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AASrB,OAAO,EAKL,KAAK,kBAAkB,EAExB,MAAM,aAAa,CAAC;AAIrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAiBlD;;;;GAIG;AACH,iBAAS,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAa3E;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAyB5B;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IA0CzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IA3CtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAM3D,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAoC;IAC3E,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAqC;IAC/E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,gBAAgB,CAAoB;IAG5C,OAAO,CAAC,sBAAsB,CAAQ;IAItC,OAAO,CAAC,sBAAsB,CAAuB;IAGrD,OAAO,CAAC,uBAAuB,CAAuB;IACtD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,qBAAqB,CAAsC;IACnE,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,kBAAkB,CAA+B;IACzD,OAAO,CAAC,qBAAqB,CAA8B;IAI3D,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,YAAY,CAAuB;gBAGxB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,aAAa;IAGrC,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAIxC,yEAAyE;IACnE,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA0L7C,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YA8Cb,kBAAkB;YAwClB,aAAa;YA0Db,wBAAwB;IA+BtC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;YA6CX,kBAAkB;YAqBlB,mBAAmB;YAgBnB,mBAAmB;YAmBnB,sBAAsB;YAwBtB,6BAA6B;IAoC3C,OAAO,CAAC,8BAA8B;IAMtC,OAAO,CAAC,uBAAuB;IAgB/B;;;;;OAKG;YACW,0BAA0B;IAiCxC,OAAO,CAAC,2BAA2B;YAIrB,cAAc;YAId,qBAAqB;YAgBrB,wBAAwB;IA+CtC,OAAO,CAAC,uBAAuB;IAU/B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,uBAAuB;IAyB/B,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,mBAAmB;YAab,mBAAmB;IAyCjC,OAAO,CAAC,wBAAwB;YAelB,qBAAqB;YAWrB,6BAA6B;IAqC3C,OAAO,CAAC,2BAA2B;IAYnC,OAAO,CAAC,wBAAwB;YAUlB,oBAAoB;IAmClC;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IASpB;;;;;;;;OAQG;YACW,sBAAsB;YA4CtB,kBAAkB;YAYlB,eAAe;YAcf,UAAU;YAoBV,cAAc;IAkE5B,OAAO,CAAC,UAAU;YA4GJ,cAAc;IAyB5B,OAAO,CAAC,0BAA0B;CAkCnC"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/supervisor.js

@@ -400,10 +400,16 @@ export class DaemonSupervisor {
         for (const profile of profiles) {
             if (profile.status !== 'running' && profile.status !== 'pending')
                 continue;
+            // The daemon supervises only machine-bound (byoc) profiles; hosted
+            // profiles (null machine_id) run on the platform pool and are never owned
+            // by a daemon machine.
+            if (!profile.machine_id)
+                continue;
+            const machineId = profile.machine_id;
             try {
                 if (profile.status === 'pending') {
                     await this.enqueueBrowserProfileLifecycle({
-                        machine_id: profile.machine_id,
+                        machine_id: machineId,
                         profile_id: profile.id,
                         action: 'open',
                     });
@@ -681,7 +687,12 @@ export class DaemonSupervisor {
         }
         if (changed) {
             this.log.info(`machine clips synced — count=${desired.length}`);
-            await this.reconnectClipProvider();
+            // Re-register the new clip set IN-STREAM rather than reconnecting the
+            // provider — a clip assign/unassign must not tear down the stream and drop
+            // in-flight invokes (the hub overwrites its set from the register; see
+            // clip-provider-sharing-design §11). Endpoint changes still rebuild via
+            // applyClipProviderState.
+            this.clipProvider?.reregister();
         }
     }
     startClipReconcileTimer() {
@@ -816,17 +827,6 @@ export class DaemonSupervisor {
         }
         return null;
     }
-    async reconnectClipProvider() {
-        if (!this.clipProvider)
-            return;
-        const provider = this.clipProvider;
-        this.clipProvider = null;
-        this.connectedClipServiceUrl = null;
-        await provider
-            .disconnect()
-            .catch((err) => this.log.warn(`clip provider reconnect disconnect failed: ${String(err)}`));
-        await this.applyClipProviderState();
-    }
     async handleWorkspaceSetupRequested(agentId) {
         if (this.spawningAgents.has(agentId)) {
             this.log.info(`agent ${agentId}: workspace setup already in progress; queueing one restart`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/daemon",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "description": "Parall local agent runtime — daemon supervisor + bridge runtimes, bundled as standalone JS files",
   "license": "MIT",
   "repository": {
@@ -16,7 +16,8 @@
     "parall-daemon": "./bundle/parall-daemon.js",
     "parall-claude-agent": "./bundle/parall-claude-agent.js",
     "parall-codex-agent": "./bundle/parall-codex-agent.js",
-    "parall-openclaw-agent": "./bundle/parall-openclaw-agent.js"
+    "parall-openclaw-agent": "./bundle/parall-openclaw-agent.js",
+    "parall-browser-pod": "./bundle/parall-browser-pod.js"
   },
   "exports": {
     ".": {
@@ -29,12 +30,13 @@
     "dist"
   ],
   "dependencies": {
+    "@aws-sdk/client-s3": "3.984.0",
     "@pinixai/bb-browser-pro": "0.15.0",
-    "@parall/agent-core": "1.35.0",
-    "@parall/sdk": "1.35.0",
-    "@parall/claude-agent": "1.35.0",
-    "@parall/codex-agent": "1.35.0",
-    "@parall/openclaw-agent": "1.35.0"
+    "@parall/sdk": "1.36.0",
+    "@parall/claude-agent": "1.36.0",
+    "@parall/openclaw-agent": "1.36.0",
+    "@parall/agent-core": "1.36.0",
+    "@parall/codex-agent": "1.36.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -44,6 +46,7 @@
   "scripts": {
     "build": "tsc -b",
     "bundle": "node ../../scripts/bundle-daemon.mjs",
-    "start": "node bundle/parall-daemon.js"
+    "start": "node bundle/parall-daemon.js",
+    "test": "pnpm run build && node --test test/*.test.mjs"
   }
 }