@parall/daemon 1.32.1 → 1.34.0

package/dist/supervisor.js

@@ -3,18 +3,21 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { effectiveLLMSourceExplicit } from '@parall/agent-core';
 import { ParallWs, } from '@parall/sdk';
-import { listDirectory } from './filesystem.js';
+import { installClip, parseSource } from './clip-runtime/clip-installer.js';
+import { parseIpcCommands } from './clip-runtime/manifest.js';
+import { BrowserProfileManager, ClipProcessManager, ClipProvider, HubClient, } from './clip-runtime/index.js';
 import { agentClaudeCredentialsFileFor, agentClaudeHomeFor, agentStateDirFor, agentWorkspaceDirFor, sharedClaudeCredentialsFileFor, } from './config.js';
+import { listDirectory } from './filesystem.js';
 import { assertAgentKey, getRuntimeAdapter } from './runtimes.js';
+import { applyRuntimeBinaryEnv } from './runtime-bin-resolver.js';
 import { prepareWorkspace } from './workspace.js';
-import { ClipProcessManager, ClipProvider } from './clip-runtime/index.js';
-import { installClip, parseSource } from './clip-runtime/clip-installer.js';
 const RUNTIME_PACKAGES = {
     'claude-code': '@parall/claude-agent',
     codex: '@parall/codex-agent',
     openclaw: '@parall/openclaw-agent',
 };
 const WORKSPACE_SETUP_RETRY_DELAY_MS = 5_000;
+const CLIP_RECONCILE_INTERVAL_MS = 5 * 60_000;
 /**
  * Sleep that wakes early on abort. Returns true if the full delay elapsed,
  * false if aborted. Used by bootstrap retry and the outer keepalive in
@@ -54,6 +57,7 @@ export class DaemonSupervisor {
     children = new Map();
     spawningAgents = new Set();
     pendingWorkspaceSetup = new Set();
+    browserProfileLifecycleQueues = new Map();
     workspaceSetupRetryTimers = new Map();
     cancelledSpawns = new Set();
     ws = null;
@@ -61,11 +65,29 @@ export class DaemonSupervisor {
     machineId = null;
     machineOrgId = null;
     machineLlmSource = 'parall';
+    // Whether this machine contributes its local clips as a hub provider. The
+    // org admin toggles it via PATCH /machines/{id}/provider-enabled; default true.
+    machineProviderEnabled = true;
+    // Externally-reachable ProviderStream endpoint delivered by the server via
+    // GET /machines/me (grey-cloud clip-rpc host). Null for hosted machines or
+    // pre-field servers; applyClipProviderState falls back to config.apiUrl.
+    machineClipProviderUrl = null;
+    // The serviceUrl the live clipProvider is currently connected to — lets
+    // applyClipProviderState detect an endpoint change and reconnect.
+    connectedClipServiceUrl = null;
     stopResolve = null;
     updater = null;
     healthConfirmed = false;
+    browserProfileManager = null;
     clipManager = null;
     clipProvider = null;
+    clipReconcileTimer = null;
+    clipReconcileInFlight = null;
+    // Execution-side hub client for cross-machine dependency resolution
+    // (GetBindings + Invoke). Cached by resolved endpoint so a clip_provider_url
+    // rollout transparently rebuilds it against the new grey-cloud host.
+    hubClient = null;
+    hubClientUrl = null;
     constructor(config, client, log) {
         this.config = config;
         this.client = client;
@@ -98,39 +120,41 @@ export class DaemonSupervisor {
         this.migrateFlatLayout();
         // Initialize Clip runtime manager (optional, for Pinix Clip subprocess management)
         if (process.env.PRLL_CLIP_RUNTIME_ENABLED === 'true') {
+            this.browserProfileManager = new BrowserProfileManager({
+                homeDir: path.join(this.config.rootStateDir, 'bb-browser'),
+                log: this.log,
+                reportStatus: (profileId, status, errorMsg) => {
+                    this.client
+                        .reportBrowserProfileStatus(profileId, status, errorMsg)
+                        .catch((err) => this.log.warn(`browser profile status report failed: ${String(err)}`));
+                },
+            });
             this.clipManager = new ClipProcessManager({
                 clipsDir: path.join(this.config.rootStateDir, 'clips'),
                 dataDir: path.join(this.config.rootStateDir, 'clip-data'),
+                browserProfileManager: this.browserProfileManager,
+                // Execution side: nested browser dependency invokes resolve their
+                // binding and route through the hub (no local shortcut).
+                hubClient: () => this.getHubClient(),
+                ensureInstalled: (config) => this.ensureClipInstalled(config),
             });
-            try {
-                await this.clipManager.loadInstalledClips();
-            }
-            catch (err) {
-                this.log.warn(`clip runtime init failed: ${String(err)}`);
-            }
-            // Connect to Clip Service as a Provider when URL is configured
-            const clipServiceUrl = process.env.PRLL_CLIP_SERVICE_URL?.trim();
-            if (clipServiceUrl && this.machineOrgId && this.machineId) {
-                this.clipProvider = new ClipProvider({
-                    serviceUrl: clipServiceUrl,
-                    authKey: this.config.apiKey,
-                    orgId: this.machineOrgId,
-                    providerName: `daemon-${this.machineId}`,
-                    clipManager: this.clipManager,
-                    log: this.log,
-                });
-                this.clipProvider
-                    .connect()
-                    .catch((err) => this.log.warn(`clip provider connect failed: ${String(err)}`));
-            }
-        }
-        // Report daemon version via heartbeat (best-effort)
-        const daemonVersion = this.updater?.getLocalVersion();
-        if (daemonVersion) {
-            this.client
-                .postMachineHeartbeat(daemonVersion)
-                .catch((err) => this.log.warn(`daemon version report failed: ${String(err)}`));
+            await this.reconcileMachineClips();
+            // Register as a hub Provider unless the machine opted out
+            // (provider_enabled=false). See applyClipProviderState.
+            await this.applyClipProviderState();
+            this.startClipReconcileTimer();
         }
+        // Report daemon version + self-update capability via heartbeat (best-effort).
+        // Capability tracks whether a service manager supervises us: the updater is
+        // created only in that case (see isSelfUpdateManaged in index.ts). A bare
+        // `npx` foreground run reports false so the server/UI won't offer a manual
+        // update it would silently ignore.
+        this.client
+            .postMachineHeartbeat({
+            daemonVersion: this.updater?.getLocalVersion(),
+            selfUpdateCapable: this.updater != null,
+        })
+            .catch((err) => this.log.warn(`daemon heartbeat report failed: ${String(err)}`));
         await this.fullReconcile();
         this.ws = new ParallWs({
             getTicket: () => this.client.getMachineWsTicket(),
@@ -185,6 +209,12 @@ export class DaemonSupervisor {
                 this.machineLlmSource = newSource;
                 void this.respawnAllChildren();
             }
+            if (data.provider_enabled !== undefined &&
+                data.provider_enabled !== this.machineProviderEnabled) {
+                this.log.info(`WS: provider_enabled changed ${this.machineProviderEnabled} → ${data.provider_enabled}`);
+                this.machineProviderEnabled = data.provider_enabled;
+                void this.applyClipProviderState();
+            }
         });
         this.ws.on('machine.workspace.setup.requested', (data) => {
             this.log.info(`WS: workspace setup requested for agent ${data.agent_id}`);
@@ -198,9 +228,13 @@ export class DaemonSupervisor {
             this.log.info(`WS: machine.stop received (reason=${data.reason ?? 'none'})`);
             void this.stop();
         });
-        this.ws.on('machine.clip.install', (data) => {
-            this.log.info(`WS: clip install requested — alias=${data.alias} source=${data.source_ref}`);
-            void this.handleClipInstall(data);
+        this.ws.on('machine.clip.sync', (data) => {
+            this.log.info(`WS: clip sync requested — clip=${data.clip_id} action=${data.action ?? ''}`);
+            void this.handleClipSync(data);
+        });
+        this.ws.on('machine.browser_profile.lifecycle', (data) => {
+            this.log.info(`WS: browser profile lifecycle requested — profile=${data.profile_id} action=${data.action}`);
+            void this.enqueueBrowserProfileLifecycle(data);
         });
         this.ws.onStateChange((state) => {
             if (state === 'disconnected' || state === 'reconnecting') {
@@ -227,6 +261,7 @@ export class DaemonSupervisor {
             clearTimeout(timer);
         }
         this.workspaceSetupRetryTimers.clear();
+        this.stopClipReconcileTimer();
         for (const state of this.children.values()) {
             state.shuttingDown = true;
             if (state.restartTimer) {
@@ -243,6 +278,10 @@ export class DaemonSupervisor {
             exits.push(this.clipManager.stopAll());
             this.clipManager = null;
         }
+        if (this.browserProfileManager) {
+            exits.push(this.browserProfileManager.stop());
+            this.browserProfileManager = null;
+        }
         await Promise.allSettled(exits);
         this.children.clear();
         this.log.info('daemon supervisor stopped');
@@ -260,6 +299,8 @@ export class DaemonSupervisor {
                 this.machineId = machine.id;
                 this.machineOrgId = machine.org_id;
                 this.machineLlmSource = machine.llm_source ?? 'parall';
+                this.machineProviderEnabled = machine.provider_enabled ?? true;
+                this.machineClipProviderUrl = machine.clip_provider_url ?? null;
                 this.log.info(`daemon online — machine_id=${machine.id} org=${machine.org_id} label=${machine.label}`);
                 return true;
             }
@@ -268,7 +309,7 @@ export class DaemonSupervisor {
                     this.log.error(`getMachineSelf failed: ${String(err)} (fail-fast mode)`);
                     throw err;
                 }
-                const delay = Math.min(this.config.bootstrapBackoffMs * Math.pow(2, attempt), this.config.bootstrapBackoffMaxMs);
+                const delay = Math.min(this.config.bootstrapBackoffMs * 2 ** attempt, this.config.bootstrapBackoffMaxMs);
                 attempt += 1;
                 this.log.warn(`getMachineSelf failed (attempt ${attempt}): ${String(err)} — retrying in ${delay}ms`);
                 const slept = await sleepCancellable(delay, signal);
@@ -331,9 +372,41 @@ export class DaemonSupervisor {
                 this.children.delete(userId);
             }
         }
-        // Reconcile desired clip installs alongside agents (best-effort; never
-        // blocks agent reconcile).
-        await this.reconcileClipInstalls();
+        // Reconcile executable Clip definitions alongside agents (best-effort;
+        // local package install remains lazy at invoke time).
+        await this.reconcileMachineClips();
+        await this.reconcileBrowserProfiles();
+    }
+    async reconcileBrowserProfiles() {
+        if (!this.browserProfileManager)
+            return;
+        let profiles;
+        try {
+            profiles = await this.client.listMachineBrowserProfiles();
+        }
+        catch (err) {
+            this.log.warn(`browser profile reconcile: list failed: ${String(err)}`);
+            return;
+        }
+        for (const profile of profiles) {
+            if (profile.status !== 'running' && profile.status !== 'pending')
+                continue;
+            try {
+                if (profile.status === 'pending') {
+                    await this.enqueueBrowserProfileLifecycle({
+                        machine_id: profile.machine_id,
+                        profile_id: profile.id,
+                        action: 'open',
+                    });
+                }
+                else {
+                    await this.browserProfileManager.ensureRuntime(profile.id);
+                }
+            }
+            catch (err) {
+                this.log.warn(`browser profile reconcile failed for ${profile.id}: ${String(err)}`);
+            }
+        }
     }
     // ---- Flat layout migration (self-hosted → daemon) ----
     /**
@@ -461,96 +534,256 @@ export class DaemonSupervisor {
             }
         }
     }
-    async handleClipInstall(data) {
-        if (!this.clipManager) {
-            this.log.warn('clip install event received but clip runtime is disabled');
-            return false;
+    async handleBrowserProfileLifecycle(data) {
+        if (!this.browserProfileManager) {
+            this.log.warn('browser profile lifecycle event received but clip runtime is disabled');
+            const status = data.action === 'stop' ? 'stopped' : 'error';
+            const error = data.action === 'stop' ? undefined : 'Browser profile runtime is disabled on this daemon';
+            await this.client.reportBrowserProfileStatus(data.profile_id, status, error).catch((err) => {
+                this.log.warn(`browser profile lifecycle negative ACK failed for ${data.profile_id}: ${String(err)}`);
+            });
+            return;
         }
         try {
-            // Idempotency guard: if the clip is already installed and running
-            // locally, a prior install succeeded but its server ACK
-            // (reportClipInstall) may have failed — the desired-state row is still
-            // pending, so reconcile re-sent the same directive. Don't re-download or
-            // restart a healthy clip; just retry the report so pending → installed.
-            if (this.clipManager.isRunning(data.alias)) {
-                this.log.info(`clip already running, re-reporting install: ${data.alias}`);
-                await this.client.reportClipInstall(data.clip_id, data.version).catch((err) => {
-                    this.log.warn(`clip install re-report failed for ${data.alias}: ${String(err)}`);
-                });
-                return true;
+            switch (data.action) {
+                case 'open':
+                    await this.browserProfileManager.openProfile(data.profile_id, data.start_url);
+                    return;
+                case 'stop':
+                    await this.browserProfileManager.stopProfile(data.profile_id);
+                    return;
+                case 'reset':
+                    await this.browserProfileManager.resetProfile(data.profile_id);
+                    return;
+                default:
+                    this.log.warn(`unknown browser profile lifecycle action: ${data.action}`);
             }
-            const clipsDir = path.join(this.config.rootStateDir, 'clips');
-            // The clip record stores a resolved version; pin the install to it when
-            // the source ref is unversioned, otherwise an unversioned source like
-            // "@pinix/github-tools" would silently fetch latest instead.
-            let source = data.source_ref;
-            if (data.version) {
-                let sourceHasVersion = false;
-                try {
-                    sourceHasVersion = !!parseSource(source).version;
-                }
-                catch {
-                    /* fall through to append */
-                }
-                if (!sourceHasVersion)
-                    source = `${source}@${data.version}`;
-            }
-            const result = await installClip({
-                source,
-                alias: data.alias,
-                clipsDir,
-                // Pinix registry REST base; falls back to the installer default when unset.
-                registryUrl: process.env.PRLL_PINIX_REGISTRY_URL?.trim() || undefined,
-            });
-            this.log.info(`clip installed: ${result.alias} v${result.version} at ${result.path}`);
-            this.clipManager.registerClip({
-                name: result.alias,
-                package: result.name,
-                version: result.version,
-                source: result.path,
-                path: result.path,
-            });
-            await this.clipManager.startClip(result.alias);
-            this.log.info(`clip started: ${result.alias}`);
-            // Report success so the server flips the desired-state row pending →
-            // installed. Reporting here (not in the caller) covers both the live WS
-            // broadcast and the durable reconcile paths with one report.
-            await this.client.reportClipInstall(data.clip_id, data.version).catch((err) => {
-                this.log.warn(`clip install report failed for ${data.alias}: ${String(err)}`);
-            });
-            return true;
         }
         catch (err) {
-            this.log.error(`clip install failed: ${String(err)}`);
-            return false;
-        }
-    }
-    // Durable reconcile: pull the registry clips this machine should have (covers
-    // installs broadcast while the daemon was offline, and clips targeted at
-    // machines that joined later), install the missing ones, and report success
-    // so the server flips the desired-state row pending → installed. Mirrors the
-    // listAttachedAgents reconcile pattern; runs on every fullReconcile.
-    async reconcileClipInstalls() {
-        if (!this.clipManager)
-            return; // clip runtime disabled — nothing to reconcile
+            this.log.warn(`browser profile lifecycle failed (profile=${data.profile_id}, action=${data.action}): ${String(err)}`);
+        }
+    }
+    enqueueBrowserProfileLifecycle(data) {
+        const previous = this.browserProfileLifecycleQueues.get(data.profile_id) ?? Promise.resolve();
+        const next = previous
+            .catch(() => {
+            // Keep the queue moving even if a prior operation failed unexpectedly.
+        })
+            .then(() => this.handleBrowserProfileLifecycle(data));
+        this.browserProfileLifecycleQueues.set(data.profile_id, next);
+        void next.finally(() => {
+            if (this.browserProfileLifecycleQueues.get(data.profile_id) === next) {
+                this.browserProfileLifecycleQueues.delete(data.profile_id);
+            }
+        });
+        return next;
+    }
+    async handleClipSync(_data) {
+        await this.reconcileMachineClips();
+    }
+    async reconcileMachineClips() {
+        if (this.clipReconcileInFlight) {
+            return this.clipReconcileInFlight;
+        }
+        const run = this.reconcileMachineClipsNow();
+        this.clipReconcileInFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (this.clipReconcileInFlight === run) {
+                this.clipReconcileInFlight = null;
+            }
+        }
+    }
+    async reconcileMachineClipsNow() {
+        if (!this.running) {
+            return;
+        }
+        const clipManager = this.clipManager;
+        if (!clipManager)
+            return;
         let desired;
         try {
-            desired = await this.client.listClipInstalls();
+            desired = await this.client.listMachineClips();
         }
         catch (err) {
-            this.log.warn(`reconcileClipInstalls: list failed: ${String(err)}`);
+            this.log.warn(`reconcileMachineClips: list failed: ${String(err)}`);
             return;
         }
-        for (const d of desired) {
-            // handleClipInstall reports success to the server on its own, so the
-            // reconcile loop just drives the install for each desired clip.
-            await this.handleClipInstall({
-                clip_id: d.clip_id,
-                alias: d.alias,
-                source_ref: d.source_ref ?? '',
-                version: d.version,
+        if (!this.running)
+            return;
+        const desiredByAlias = new Map(desired.map((clip) => [clip.alias, clip]));
+        const registeredByName = new Map(clipManager.getRegisteredClips().map((c) => [c.name, c]));
+        let changed = false;
+        for (const registered of clipManager.getRegisteredClips()) {
+            if (desiredByAlias.has(registered.name))
+                continue;
+            await clipManager.unregisterClip(registered.name);
+            registeredByName.delete(registered.name);
+            changed = true;
+        }
+        for (const clip of desired) {
+            const config = this.machineClipToConfig(clip);
+            const existing = registeredByName.get(config.name);
+            if (!existing) {
+                clipManager.registerClip(config);
+                registeredByName.set(config.name, config);
+                changed = true;
+            }
+            else if (this.clipConfigSignature(existing) !== this.clipConfigSignature(config)) {
+                await clipManager.replaceClipConfig(config);
+                registeredByName.set(config.name, config);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.log.info(`machine clips synced — count=${desired.length}`);
+            await this.reconnectClipProvider();
+        }
+    }
+    startClipReconcileTimer() {
+        if (this.clipReconcileTimer || !this.clipManager)
+            return;
+        this.clipReconcileTimer = setInterval(() => {
+            void this.reconcileMachineClips().catch((err) => {
+                this.log.warn(`periodic clip reconcile failed: ${String(err)}`);
             });
+        }, CLIP_RECONCILE_INTERVAL_MS);
+        this.clipReconcileTimer.unref?.();
+    }
+    stopClipReconcileTimer() {
+        if (!this.clipReconcileTimer)
+            return;
+        clearInterval(this.clipReconcileTimer);
+        this.clipReconcileTimer = null;
+    }
+    machineClipToConfig(clip) {
+        const clipPath = path.join(this.config.rootStateDir, 'clips', clip.alias);
+        return {
+            clipId: clip.clip_id,
+            name: clip.alias,
+            package: clip.name,
+            version: clip.version,
+            source: clip.source_ref ?? clip.name,
+            sourceType: clip.source_type,
+            sourceRef: clip.source_ref,
+            path: clipPath,
+            manifest: this.manifestFromMachineClip(clip),
+        };
+    }
+    manifestFromMachineClip(clip) {
+        const raw = clip.manifest ?? {};
+        const commands = parseIpcCommands(raw.commands ?? raw.commandDetails ?? raw.command_details ?? raw.tools);
+        return {
+            name: clip.alias,
+            package: String(raw.package ?? raw.name ?? clip.name),
+            version: String(raw.version ?? clip.version ?? ''),
+            domain: typeof raw.domain === 'string' ? raw.domain : undefined,
+            description: typeof raw.description === 'string' ? raw.description : (clip.description ?? undefined),
+            commands: commands.map((c) => c.name),
+            commandDetails: commands,
+            hasWeb: Boolean(raw.hasWeb ?? raw.has_web ?? false),
+            dependencies: this.dependencyMap(raw.dependencies),
+            dependencySlots: this.dependencyMap(raw.dependencySlots ?? raw.dependency_slots),
+            patterns: Array.isArray(raw.patterns) ? raw.patterns.map(String) : undefined,
+            entities: raw.entities && typeof raw.entities === 'object'
+                ? raw.entities
+                : undefined,
+        };
+    }
+    dependencyMap(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const out = {};
+        for (const [key, raw] of Object.entries(value)) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                continue;
+            const item = raw;
+            out[key] = {
+                package: typeof item.package === 'string' ? item.package : undefined,
+                version: typeof item.version === 'string' ? item.version : undefined,
+            };
+        }
+        return out;
+    }
+    clipConfigSignature(config) {
+        return JSON.stringify({
+            clipId: config.clipId,
+            name: config.name,
+            package: config.package,
+            version: config.version,
+            sourceType: config.sourceType,
+            sourceRef: config.sourceRef,
+            path: config.path,
+            manifest: config.manifest,
+        });
+    }
+    async ensureClipInstalled(config) {
+        if (config.sourceType !== 'registry') {
+            return config;
+        }
+        const sourceRef = config.sourceRef?.trim();
+        if (!sourceRef) {
+            throw new Error(`registry clip "${config.name}" is missing source_ref`);
+        }
+        const expectedPath = path.join(this.config.rootStateDir, 'clips', config.name);
+        const localVersion = this.readInstalledClipVersion(expectedPath);
+        if (localVersion && (!config.version || localVersion === config.version)) {
+            return { ...config, path: expectedPath, source: expectedPath };
+        }
+        let source = sourceRef;
+        if (config.version) {
+            let sourceHasVersion = false;
+            try {
+                sourceHasVersion = !!parseSource(source).version;
+            }
+            catch {
+                /* fall through to append */
+            }
+            if (!sourceHasVersion)
+                source = `${source}@${config.version}`;
         }
+        const result = await installClip({
+            source,
+            alias: config.name,
+            clipsDir: path.join(this.config.rootStateDir, 'clips'),
+            registryUrl: process.env.PRLL_PINIX_REGISTRY_URL?.trim() || undefined,
+        });
+        this.log.info(`clip ensured: ${result.alias} v${result.version} at ${result.path}`);
+        return {
+            ...config,
+            package: result.name,
+            version: result.version,
+            source: result.path,
+            path: result.path,
+        };
+    }
+    readInstalledClipVersion(dir) {
+        for (const file of ['clip.json', 'package.json']) {
+            try {
+                const raw = fs.readFileSync(path.join(dir, file), 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.version === 'string' && parsed.version.trim()) {
+                    return parsed.version.trim();
+                }
+            }
+            catch {
+                // try the next metadata file
+            }
+        }
+        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)) {
@@ -617,11 +850,109 @@ export class DaemonSupervisor {
                 this.machineLlmSource = newSource;
                 await this.respawnAllChildren();
             }
+            const newProviderEnabled = machine.provider_enabled ?? true;
+            const newClipProviderUrl = machine.clip_provider_url ?? null;
+            const providerEnabledChanged = newProviderEnabled !== this.machineProviderEnabled;
+            const clipProviderUrlChanged = newClipProviderUrl !== this.machineClipProviderUrl;
+            if (providerEnabledChanged) {
+                this.log.info(`machine config refreshed: provider_enabled ${this.machineProviderEnabled} → ${newProviderEnabled}`);
+                this.machineProviderEnabled = newProviderEnabled;
+            }
+            if (clipProviderUrlChanged) {
+                this.log.info(`machine config refreshed: clip_provider_url ${this.machineClipProviderUrl ?? '(none)'} → ${newClipProviderUrl ?? '(none)'}`);
+                this.machineClipProviderUrl = newClipProviderUrl;
+            }
+            if (providerEnabledChanged || clipProviderUrlChanged) {
+                await this.applyClipProviderState();
+            }
         }
         catch (err) {
             this.log.warn(`refreshMachineConfig failed: ${String(err)}`);
         }
     }
+    /**
+     * Resolve the ProviderStream endpoint the daemon registers clips against.
+     * Priority: PRLL_CLIP_SERVICE_URL (hosted/cluster DNS or explicit operator
+     * override) > machine.clip_provider_url (server-delivered grey-cloud
+     * clip-rpc host for BYOC) > config.apiUrl (legacy fallback for servers
+     * predating clip_provider_url). The grey-cloud host bypasses Cloudflare's
+     * proxy, which does not pass Connect-RPC bidi streams (#1430).
+     */
+    resolveClipServiceUrl() {
+        return (process.env.PRLL_CLIP_SERVICE_URL?.trim() ||
+            this.machineClipProviderUrl?.trim() ||
+            this.config.apiUrl);
+    }
+    /**
+     * Execution-side hub client used to resolve a Clip's dependency
+     * binding (GetBindings) and forward the dependency invoke (Invoke). It targets
+     * the same grey-cloud clip-rpc endpoint as the provider stream and auths with
+     * the daemon's mck_ (the hub scope-gates calls to instances this machine
+     * executes). Rebuilt transparently when the resolved endpoint changes.
+     */
+    getHubClient() {
+        const serviceUrl = this.resolveClipServiceUrl();
+        if (!serviceUrl)
+            return null;
+        if (this.hubClient && this.hubClientUrl === serviceUrl)
+            return this.hubClient;
+        this.hubClient = new HubClient({ serviceUrl, authKey: this.config.apiKey });
+        this.hubClientUrl = serviceUrl;
+        return this.hubClient;
+    }
+    /**
+     * Connect, reconnect, or disconnect the clip Provider to match
+     * machineProviderEnabled and the resolved ProviderStream endpoint. An org
+     * admin toggles provider_enabled to withdraw the machine from the org clip
+     * provider pool without uninstalling clips; a changed clip_provider_url
+     * triggers a transparent reconnect to the new endpoint. No-op when the clip
+     * runtime is disabled or identity is not yet resolved. See
+     * docs/engineering-design/clip-provider-sharing-design.md.
+     */
+    async applyClipProviderState() {
+        if (!this.clipManager || !this.machineOrgId || !this.machineId)
+            return;
+        if (this.machineProviderEnabled) {
+            const serviceUrl = this.resolveClipServiceUrl();
+            if (this.clipProvider) {
+                if (this.connectedClipServiceUrl === serviceUrl)
+                    return; // already on the right endpoint
+                // Endpoint changed → tear down the stale stream before reconnecting.
+                this.log.info(`clip provider endpoint changed → reconnecting (${serviceUrl})`);
+                const stale = this.clipProvider;
+                this.clipProvider = null;
+                await stale
+                    .disconnect()
+                    .catch((err) => this.log.warn(`clip provider disconnect (endpoint change) failed: ${String(err)}`));
+            }
+            this.connectedClipServiceUrl = serviceUrl;
+            this.clipProvider = new ClipProvider({
+                serviceUrl,
+                authKey: this.config.apiKey,
+                orgId: this.machineOrgId,
+                providerName: `daemon-${this.machineId}`,
+                clipManager: this.clipManager,
+                log: this.log,
+                // Self-heal: if the provider can't reach its endpoint for a while, the
+                // server may have rolled out a (new) clip_provider_url after we booted
+                // (our ws-gateway WS never bounced to re-trigger machine.hello). Refetch
+                // machine config; applyClipProviderState rebuilds us if the URL moved.
+                onPersistentFailure: () => void this.refreshMachineConfig(),
+            });
+            this.clipProvider
+                .connect()
+                .catch((err) => this.log.warn(`clip provider connect failed: ${String(err)}`));
+        }
+        else if (this.clipProvider) {
+            this.log.info('clip provider disabled (provider_enabled=false) — disconnecting');
+            const provider = this.clipProvider;
+            this.clipProvider = null;
+            this.connectedClipServiceUrl = null;
+            await provider
+                .disconnect()
+                .catch((err) => this.log.warn(`clip provider disconnect failed: ${String(err)}`));
+        }
+    }
     async respawnAllChildren() {
         const states = [...this.children.values()];
         for (const state of states) {
@@ -744,9 +1075,10 @@ export class DaemonSupervisor {
             workspaceDir: state.workspacePath,
             claudeHome: state.claudeHome,
         };
-        const baseEnv = { ...process.env, PRLL_API_URL: this.config.apiUrl };
+        let baseEnv = { ...process.env, PRLL_API_URL: this.config.apiUrl };
         if (this.machineId)
             baseEnv.PRLL_MACHINE_ID = this.machineId;
+        baseEnv = applyRuntimeBinaryEnv(state.runtimeType, baseEnv, this.log);
         // An explicit per-agent provider_config (llm_source or BYO creds) wins;
         // otherwise defer to the CURRENT machine-level llm_source. The server sends
         // an empty `{}` for self-hosted agents (per-agent provider_config is
@@ -783,7 +1115,7 @@ export class DaemonSupervisor {
             }
             if (wasShutting || !this.running)
                 return;
-            const delay = Math.min(this.config.restartBackoffMs * Math.pow(2, state.restartAttempts), this.config.restartBackoffMaxMs);
+            const delay = Math.min(this.config.restartBackoffMs * 2 ** state.restartAttempts, this.config.restartBackoffMaxMs);
             state.restartAttempts += 1;
             this.log.warn(`agent ${state.agentId} will restart in ${delay}ms`);
             state.restartTimer = setTimeout(() => {