@camstack/server 1.1.76 → 1.2.1

package/dist/agent/agent-service.js

@@ -0,0 +1,595 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDeployAction = resolveDeployAction;
+exports.createAgentService = createAgentService;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const system_1 = require("@camstack/system");
+const moleculer_1 = require("moleculer");
+const agent_deploy_swap_js_1 = require("./agent-deploy-swap.js");
+const apply_model_distribution_js_1 = require("./apply-model-distribution.js");
+const fetch_bundle_from_hub_js_1 = require("./fetch-bundle-from-hub.js");
+/**
+ * Console-backed scoped logger for the deploy swap (the only consumer in this
+ * file). `applyDeployedBundle` logs only on the rare restore-after-failed-swap
+ * path, so a thin console adapter is sufficient.
+ */
+const deploySwapLogger = {
+    info: (msg) => console.log(`[Agent] ${msg}`),
+    warn: (msg) => console.warn(`[Agent] ${msg}`),
+    error: (msg) => console.error(`[Agent] ${msg}`),
+    debug: (msg) => console.debug(`[Agent] ${msg}`),
+    child: () => deploySwapLogger,
+    withTags: () => deploySwapLogger,
+};
+/** Timeout for the agent-local `$process.restart` delegation. */
+const AGENT_PROCESS_RESTART_TIMEOUT_MS = 30_000;
+function getLocalIps() {
+    const interfaces = os.networkInterfaces();
+    const ips = [];
+    for (const ifaces of Object.values(interfaces)) {
+        if (!ifaces)
+            continue;
+        for (const iface of ifaces) {
+            if (iface.internal)
+                continue;
+            ips.push(iface.address);
+        }
+    }
+    return ips;
+}
+/**
+ * Resolve a promise but never block longer than `ms` — on timeout, resolve to
+ * `fallback`. `$agent.status`/`$agent.health` MUST always answer promptly: the
+ * hub drops a node from `nodes.topology` whenever `$agent.status` times out, so
+ * a status RPC that hangs on a transiently-unavailable metrics provider (e.g.
+ * mid-reload) makes the agent silently vanish from the cluster. Bounding the
+ * metrics fetch keeps the node visible with a degraded (zeroed) metrics block
+ * instead of disappearing.
+ */
+async function withTimeout(p, ms, fallback) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(fallback), ms);
+    });
+    try {
+        return await Promise.race([p, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Bound for the metrics snapshot inside status/health — see `withTimeout`. */
+const METRICS_SNAPSHOT_TIMEOUT_MS = 2_000;
+/**
+ * Pure factory that builds the deploy routing logic from a seam. Exported so
+ * the routing can be unit-tested without Moleculer or a real filesystem.
+ */
+function resolveDeployAction(seam) {
+    return async (params) => {
+        const { addonId, source, bundle } = params;
+        if (source && (0, system_1.isAddonDeploySource)(source)) {
+            if (source.kind === 'npm') {
+                await seam.installFromNpm(addonId, source.version);
+                // npm path installs to disk via AddonInstaller and returns no addonDir; the
+                // loadedAddons eviction (onApplied) only applies to bundle-extracted installs.
+                return { success: true, addonId };
+            }
+            const buf = await seam.fetchBundle(source);
+            const { addonDir } = await seam.applyBundle(buf);
+            seam.onApplied(addonDir);
+            return { success: true, addonId, path: addonDir };
+        }
+        // Legacy inline-bundle path (back-compat, removed next release).
+        if (bundle === undefined) {
+            throw new Error('$agent.deploy: no source descriptor and no legacy bundle provided');
+        }
+        const buf = typeof bundle === 'string' ? Buffer.from(bundle, 'base64') : bundle;
+        const { addonDir } = await seam.applyBundle(buf);
+        seam.onApplied(addonDir);
+        return { success: true, addonId, path: addonDir };
+    };
+}
+function readHubAddressFromConfig(configPath) {
+    if (!configPath)
+        return null;
+    try {
+        if (!fs.existsSync(configPath))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        return typeof raw.hubAddress === 'string' && raw.hubAddress.length > 0 ? raw.hubAddress : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the addon declaration ids contributed by a deployed package.
+ *
+ * `loadedAddons` is keyed by `camstack.addons[].id` (the declaration
+ * id), not the package name. A redeploy's `$agent.deploy` param is the
+ * package name, so the deploy handler reads the freshly-extracted
+ * `package.json` to recover the real ids it must evict before
+ * `$agent.reload`. Best-effort — returns `[]` on a missing/corrupt
+ * manifest (the reload then just falls back to its on-disk scan).
+ */
+function readDeployedAddonIds(addonDir) {
+    try {
+        const manifestPath = path.join(addonDir, 'package.json');
+        if (!fs.existsSync(manifestPath))
+            return [];
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        const entries = raw.camstack?.addons ?? [];
+        const ids = [];
+        for (const entry of entries) {
+            if (typeof entry.id === 'string' && entry.id.length > 0)
+                ids.push(entry.id);
+        }
+        return ids;
+    }
+    catch {
+        return [];
+    }
+}
+function isHubConnected(broker) {
+    try {
+        const registry = broker.registry;
+        const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? [];
+        return nodes.some((n) => n.id === 'hub');
+    }
+    catch {
+        return false;
+    }
+}
+function createAgentService(deps) {
+    return {
+        name: '$agent',
+        actions: {
+            status: {
+                handler: async (ctx) => {
+                    const { broker } = ctx;
+                    const cpus = os.cpus();
+                    let cpuPercent = 0;
+                    let memoryPercent = 0;
+                    const metrics = deps.getMetricsProvider?.();
+                    if (metrics) {
+                        // Bounded so $agent.status never hangs (and drops the node from
+                        // topology) when the metrics provider is mid-reload/unavailable.
+                        const snapshot = await withTimeout(metrics.getCached(), METRICS_SNAPSHOT_TIMEOUT_MS, null);
+                        if (snapshot) {
+                            cpuPercent = snapshot.cpu.total;
+                            memoryPercent = snapshot.memory.percent;
+                        }
+                    }
+                    const mem = process.memoryUsage();
+                    return {
+                        nodeId: broker.nodeID,
+                        name: deps.agentName,
+                        platform: os.platform(),
+                        arch: os.arch(),
+                        hostname: os.hostname(),
+                        cpuCores: cpus.length,
+                        cpuModel: cpus[0]?.model,
+                        totalMemoryMB: Math.round(os.totalmem() / 1024 / 1024),
+                        freeMemoryMB: Math.round(os.freemem() / 1024 / 1024),
+                        cpuPercent,
+                        memoryPercent,
+                        uptime: os.uptime(),
+                        // The agent *process* itself (distinct from the host `uptime` /
+                        // memory above) — surfaced so the UI can show how long THIS agent
+                        // has been running and how much RAM its own runtime holds.
+                        agentProcess: {
+                            pid: process.pid,
+                            uptimeSeconds: Math.round(process.uptime()),
+                            rssMB: Math.round(mem.rss / 1024 / 1024),
+                            heapUsedMB: Math.round(mem.heapUsed / 1024 / 1024),
+                            heapTotalMB: Math.round(mem.heapTotal / 1024 / 1024),
+                        },
+                        localIps: getLocalIps(),
+                        addons: [...deps.loadedAddons.values()].map((a) => ({
+                            id: a.id,
+                            status: a.status,
+                            // Report the PACKAGE version (falls back to the declaration
+                            // version) so the hub's per-node update check is accurate.
+                            version: a.packageVersion ?? a.version,
+                            packageName: a.packageName,
+                        })),
+                    };
+                },
+            },
+            health: {
+                handler: async (ctx) => {
+                    const { broker } = ctx;
+                    let cpuPercent = 0;
+                    let memoryPercent = 0;
+                    const metrics = deps.getMetricsProvider?.();
+                    if (metrics) {
+                        try {
+                            // Bounded — see $agent.status. Health must answer promptly too.
+                            const snapshot = await withTimeout(metrics.getCached(), METRICS_SNAPSHOT_TIMEOUT_MS, null);
+                            if (snapshot) {
+                                cpuPercent = snapshot.cpu.total;
+                                memoryPercent = snapshot.memory.percent;
+                            }
+                        }
+                        catch {
+                            /* metrics may be transiently unavailable */
+                        }
+                    }
+                    let total = 0;
+                    let running = 0;
+                    let errored = 0;
+                    for (const a of deps.loadedAddons.values()) {
+                        total++;
+                        if (a.status === 'running')
+                            running++;
+                        else if (a.status === 'error')
+                            errored++;
+                    }
+                    const hubAddress = readHubAddressFromConfig(deps.configPath);
+                    return {
+                        ok: errored === 0,
+                        nodeId: broker.nodeID,
+                        name: deps.agentName,
+                        version: deps.agentVersion ?? 'unknown',
+                        uptimeSeconds: Math.round(process.uptime()),
+                        pid: process.pid,
+                        hubConnected: isHubConnected(broker),
+                        hubAddress,
+                        addons: { total, running, error: errored },
+                        cpuPercent,
+                        memoryPercent,
+                        checkedAt: new Date().toISOString(),
+                    };
+                },
+            },
+            shutdown: {
+                handler() {
+                    // Graceful shutdown — schedule so the Moleculer response goes out first
+                    setTimeout(() => process.exit(0), 500);
+                    return { success: true };
+                },
+            },
+            rename: {
+                handler(ctx) {
+                    const { params, broker } = ctx;
+                    const newName = params.name;
+                    if (!newName || typeof newName !== 'string') {
+                        throw new Error('$agent.rename: name is required');
+                    }
+                    const oldName = deps.agentName;
+                    // Update in-memory name (affects subsequent $agent.status responses)
+                    deps.agentName = newName.trim();
+                    broker.logger.info(`Agent renamed: "${oldName}" → "${deps.agentName}"`);
+                    // Persist to config file
+                    try {
+                        const configFile = path.resolve(deps.configPath);
+                        let raw = {};
+                        if (fs.existsSync(configFile)) {
+                            try {
+                                raw = JSON.parse(fs.readFileSync(configFile, 'utf-8'));
+                            }
+                            catch {
+                                /* corrupt */
+                            }
+                        }
+                        raw.name = deps.agentName;
+                        fs.mkdirSync(path.dirname(configFile), { recursive: true });
+                        fs.writeFileSync(configFile, JSON.stringify(raw, null, 2), 'utf-8');
+                        broker.logger.info(`Agent name persisted to ${configFile}`);
+                    }
+                    catch (err) {
+                        broker.logger.warn('Agent rename: config file write failed (in-memory rename still active)', { error: String(err) });
+                    }
+                    return { success: true, name: deps.agentName };
+                },
+            },
+            listAddons: {
+                handler() {
+                    return [...deps.loadedAddons.keys()];
+                },
+            },
+            deploy: {
+                handler: async (ctx) => {
+                    const { params } = ctx;
+                    const { addonId, source, bundle } = params;
+                    // execFile (no shell) instead of execSync — addonId comes from RPC
+                    // params and was previously interpolated into a shell command, which
+                    // is a command-injection vector. argv form doesn't go through a shell
+                    // so any payload in addonId stays a literal path arg. Use the ASYNC
+                    // form (not execFileSync): a synchronous extract blocks the agent
+                    // event loop for the whole untar, which on a large package starves
+                    // concurrent hub RPCs ($agent.status heartbeat) long enough for the
+                    // hub to time them out and drop the node from topology mid-deploy.
+                    const { execFile } = await Promise.resolve().then(() => __importStar(require('node:child_process')));
+                    const { promisify } = await Promise.resolve().then(() => __importStar(require('node:util')));
+                    const execFileAsync = promisify(execFile);
+                    // Atomic install: extract into a temp dir then swap into place. The
+                    // old body `rm`'d the live dir THEN untarred — a killed/timed-out
+                    // untar (e.g. a redeploy whose RPC was cut) left the addon dir
+                    // MISSING. `applyDeployedBundle` never leaves the live dir absent
+                    // (the non-atomic-deploy fix).
+                    const extract = async (tgz, destDir) => {
+                        const tgzPath = path.join(destDir, '..', `.${path.basename(destDir)}.tgz`);
+                        fs.writeFileSync(tgzPath, tgz);
+                        try {
+                            await execFileAsync('tar', ['-xzf', tgzPath, '-C', destDir, '--strip-components=1'], {
+                                timeout: 60000,
+                            });
+                        }
+                        finally {
+                            try {
+                                fs.unlinkSync(tgzPath);
+                            }
+                            catch {
+                                /* best-effort temp cleanup */
+                            }
+                        }
+                    };
+                    const seam = {
+                        installFromNpm: (pkg, v) => {
+                            if (!deps.installFromNpm) {
+                                throw new Error('npm deploy source unsupported on this agent');
+                            }
+                            return deps.installFromNpm(pkg, v);
+                        },
+                        // #17: route the bundle through the agent's AddonInstaller when
+                        // wired — installFromTgz runs the FULL post-install (manifest
+                        // strip, runtime-deps npm install, manifest-driven NATIVE deps)
+                        // with its own staged extract + atomic swap. The plain tar swap
+                        // below never installed deps, so every pipeline/post-analysis
+                        // deploy on the Mac Electron agent silently shipped without
+                        // `sharp` et al. Fallback kept for agents without an installer
+                        // (test harnesses).
+                        applyBundle: async (buf) => {
+                            if (deps.installBundleTgz) {
+                                const tgzPath = path.join(os.tmpdir(), `camstack-deploy-${addonId.replace(/[^\w.-]/g, '_')}-${Date.now()}.tgz`);
+                                fs.writeFileSync(tgzPath, buf);
+                                try {
+                                    const { name } = await deps.installBundleTgz(tgzPath);
+                                    return { addonDir: path.join(deps.addonsDir, name) };
+                                }
+                                finally {
+                                    try {
+                                        fs.unlinkSync(tgzPath);
+                                    }
+                                    catch {
+                                        /* best-effort temp cleanup */
+                                    }
+                                }
+                            }
+                            return (0, agent_deploy_swap_js_1.applyDeployedBundle)({
+                                addonsDir: deps.addonsDir,
+                                addonId,
+                                bundle: buf,
+                                extract,
+                                logger: deploySwapLogger,
+                            });
+                        },
+                        fetchBundle: (s) => (0, fetch_bundle_from_hub_js_1.fetchBundleFromHub)(s),
+                        // Evict every addon DECLARATION id this package contributes
+                        // from `loadedAddons` so the follow-up `$agent.reload` actually
+                        // re-instantiates it. `loadDeployedAddons` skips any addon
+                        // still present in `loadedAddons`; without this eviction a
+                        // redeploy would leave the agent pinned to the pre-update
+                        // version. The `deploy` param `addonId` is the PACKAGE name
+                        // (used only as the on-disk dir), whereas `loadedAddons` is
+                        // keyed by the addon DECLARATION id — they differ for scoped
+                        // packages, so we read the extracted manifest to bridge them.
+                        onApplied: (addonDir) => {
+                            for (const declId of readDeployedAddonIds(addonDir)) {
+                                deps.loadedAddons.delete(declId);
+                            }
+                        },
+                    };
+                    return resolveDeployAction(seam)({ addonId, source, bundle });
+                },
+            },
+            /**
+             * Pull a staged model tarball from the hub and untar it into this node's
+             * `<dataDir>/models` (Model Studio P2). Reuses the agent-pull machinery:
+             * `fetchBundleFromHub` verifies bytes + sha256 before extraction. The
+             * existing `isModelDownloaded` then reports the model present, so the
+             * detection-pipeline can load it locally.
+             */
+            distributeModel: {
+                handler: async (ctx) => {
+                    const { params } = ctx;
+                    const { execFile } = await Promise.resolve().then(() => __importStar(require('node:child_process')));
+                    const { promisify } = await Promise.resolve().then(() => __importStar(require('node:util')));
+                    const execFileAsync = promisify(execFile);
+                    const modelsDir = path.join(deps.dataDir, 'models');
+                    const seam = {
+                        modelsDir,
+                        fetchBundle: (s) => (0, fetch_bundle_from_hub_js_1.fetchBundleFromHub)(s),
+                        extract: async (tgz, destDir) => {
+                            const tmp = path.join(destDir, `.dist-${Date.now()}-${Math.random().toString(36).slice(2)}.tgz`);
+                            fs.writeFileSync(tmp, tgz);
+                            try {
+                                await execFileAsync('tar', ['-xzf', tmp, '-C', destDir], { timeout: 60000 });
+                            }
+                            finally {
+                                try {
+                                    fs.unlinkSync(tmp);
+                                }
+                                catch {
+                                    /* best-effort temp cleanup */
+                                }
+                            }
+                        },
+                        mkdirp: (dir) => fs.mkdirSync(dir, { recursive: true }),
+                    };
+                    return (0, apply_model_distribution_js_1.applyModelDistribution)(seam, params);
+                },
+            },
+            /**
+             * Genuinely drop a deployed addon from this agent.
+             *
+             * A plain `loadedAddons.delete()` only forgets the bookkeeping entry —
+             * the addon instance keeps running and, crucially, its Moleculer
+             * service keeps advertising the addon's capabilities into the cluster
+             * (the hub still sees the provider as a live `<cap>@<agent>` entry).
+             * To truly undeploy we must, in order:
+             *   1. `shutdown()` the running instance (releases timers, sockets,
+             *      native handles) — same hook the agent's SIGTERM path uses.
+             *   2. `broker.destroyService(addonId)` — the deployed-addon Moleculer
+             *      service is named after the addon DECLARATION id (see
+             *      `createAddonService` → `name: declaration.id`). Destroying it
+             *      unregisters every capability action so the cluster stops
+             *      routing to / advertising this agent's provider.
+             *   3. Drop the `loadedAddons` entry and delete the on-disk folder.
+             *
+             * `addonId` here is the addon DECLARATION id — the same key
+             * `loadedAddons` uses and the same value `$agent.status` reports, so
+             * the hub reconciler can match it directly.
+             */
+            undeploy: {
+                handler: async (ctx) => {
+                    const { params, broker } = ctx;
+                    const { addonId } = params;
+                    const entry = deps.loadedAddons.get(addonId);
+                    // 1. Shut the running instance down (best-effort — a throwing
+                    //    disposer must not block the rest of the teardown).
+                    if (entry?.addon?.shutdown) {
+                        try {
+                            await entry.addon.shutdown();
+                        }
+                        catch (err) {
+                            broker.logger.warn(`$agent.undeploy: ${addonId} shutdown() threw`, {
+                                error: String(err),
+                            });
+                        }
+                    }
+                    // 2. Destroy the Moleculer service so the cluster stops seeing
+                    //    this agent's capability providers for the addon.
+                    try {
+                        await broker.destroyService(addonId);
+                    }
+                    catch {
+                        // Service may not exist (group-spawned addons have no per-addon
+                        // service on the agent broker, or it was never created).
+                    }
+                    // 3. Forget the entry and remove the deployed folder. The deploy
+                    //    handler keys the on-disk dir by the PACKAGE name, but $agent
+                    //    redeploys for a single addon use addonId === packageName for
+                    //    unscoped packages; remove whichever folder matches.
+                    deps.loadedAddons.delete(addonId);
+                    const addonDir = path.join(deps.addonsDir, addonId);
+                    if (fs.existsSync(addonDir)) {
+                        fs.rmSync(addonDir, { recursive: true, force: true });
+                    }
+                    // Defense-in-depth: one package dir can host MANY addons (e.g.
+                    // `@camstack/addon-pipeline` ships decoder-ffmpeg, recorder,
+                    // motion-wasm, …). Removing the whole bundle because ONE member was
+                    // undeployed is destructive — every sibling runner would crash-loop
+                    // on the missing package.json. Only remove the package dir when no
+                    // OTHER loaded addon still lives in it (this addon's own entry was
+                    // already deleted from `loadedAddons` above, so the remaining
+                    // values are exactly the siblings).
+                    const pkgName = entry?.packageName;
+                    if (pkgName && pkgName !== addonId) {
+                        const pkgShared = [...deps.loadedAddons.values()].some((e) => e.packageName === pkgName);
+                        if (!pkgShared) {
+                            const pkgDir = path.join(deps.addonsDir, pkgName);
+                            if (fs.existsSync(pkgDir)) {
+                                fs.rmSync(pkgDir, { recursive: true, force: true });
+                            }
+                        }
+                    }
+                    broker.logger.info(`$agent.undeploy: ${addonId} disposed (instance + service + folder)`);
+                    return { success: true, addonId };
+                },
+            },
+            /**
+             * Re-run `loadDeployedAddons` so addons just dropped onto disk via
+             * `$agent.deploy` (or via the hub broadcasting an upload) start
+             * immediately. Without this the agent only discovers them on boot.
+             * Returns the ids that were newly loaded — the hub uses this to
+             * surface a per-agent diff in the upload response.
+             */
+            reload: {
+                handler: async () => {
+                    if (!deps.reloadDeployedAddons) {
+                        return { success: false, loaded: [] };
+                    }
+                    const loaded = await deps.reloadDeployedAddons();
+                    return { success: true, loaded };
+                },
+            },
+            restart: {
+                handler: async (ctx) => {
+                    const { params, broker } = ctx;
+                    const { addonId } = params;
+                    // Delegate to THIS agent's own `$process` service — the SAME primitive
+                    // the hub uses for a local forked addon (AddonRegistryService.restartAddon
+                    // → `$process.restart`). `resolveRunnerName` maps `addonId` to its hosting
+                    // runner (direct runner key OR `runnerAddons` membership), so the child is
+                    // respawned, the crash streak reset (`crashSupervisor.reset`), the stale
+                    // Moleculer node evicted, and the addon's caps re-registered — identical
+                    // semantics to a hub-local restart. Pin to the agent's own node so the
+                    // call always hits THIS agent's `$process`, never the hub's.
+                    const result = await broker.call('$process.restart', { name: addonId }, { nodeID: broker.nodeID, timeout: AGENT_PROCESS_RESTART_TIMEOUT_MS });
+                    if (!result.success) {
+                        // Fail loudly so the hub's `nodes.restartAddon` surfaces the real
+                        // error instead of the old fire-and-forget phantom success.
+                        throw new moleculer_1.Errors.MoleculerError(`$agent.restart: process restart failed for "${addonId}": ${result.reason ?? 'unknown'}`, 500, 'AGENT_RESTART_FAILED');
+                    }
+                    return { success: true, addonId, pid: result.pid };
+                },
+            },
+            /**
+             * D3 subtree aggregation: a forked group-runner child calls this action
+             * to deliver its complete capability manifest to the agent. The agent
+             * then re-registers the UNION of its own in-process addons + all children
+             * with the hub via `$hub.registerNode`.
+             */
+            registerNode: {
+                handler(ctx) {
+                    const { params } = ctx;
+                    // Cluster-secret gate: when the agent has a secret configured, a child
+                    // runner must present a matching hash or the registration is rejected.
+                    if (!(0, system_1.clusterSecretMatches)(deps.expectedClusterSecretHash, params.clusterSecretHash)) {
+                        throw new moleculer_1.Errors.MoleculerError(`cluster secret mismatch — node "${params.nodeId}" rejected`, 403, system_1.CLUSTER_SECRET_MISMATCH_TYPE);
+                    }
+                    deps.onChildRegistered?.(params);
+                    return { ok: true };
+                },
+            },
+        },
+    };
+}