@camstack/server 1.2.675 → 1.2.677

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.677] - 2026-10-28
+
+### Changed
+
+- An agent now keeps its own server closure current: unpaired it follows the npm latest, paired it follows the hub's version, checked at boot and every 6 hours (turn off with CAMSTACK_AGENT_SELF_UPDATE=off).
+
+## [1.2.676] - 2026-10-28
+
+### Fixed
+
+- An agent advertises itself on the network again, so the hub lists a new agent for pairing without typing its address
+- An unpaired agent no longer crash-loops: it stays up to be paired and starts its addons once pairing completes
+
 ## [1.2.675] - 2026-10-28
 
 ### Changed

package/dist/agent/agent-boot-mode.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideAgentBootMode = decideAgentBootMode;
+function decideAgentBootMode(input) {
+    return input.paired ? 'full' : 'pairing-only';
+}

package/dist/agent/agent-hub-registration.js

@@ -50,9 +50,9 @@ function createAgentHubRegistration(opts) {
                     opts.onCertificateRefused?.(err);
             },
         })
-            .then(() => {
+            .then((ack) => {
             opts.log(`[register-node] the hub acked this node's capabilities: ${manifest.addons.length} addon(s), ${bindings} binding(s) (${reason})`);
-            opts.onAcked?.();
+            opts.onAcked?.((0, system_1.hubServerVersionOf)(ack));
         })
             .catch(() => {
             // Aborted: shutting down.

package/dist/agent/agent-self-update.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideAgentSelfUpdate = decideAgentSelfUpdate;
+exports.agentSelfUpdateEnabled = agentSelfUpdateEnabled;
+exports.runAgentSelfUpdate = runAgentSelfUpdate;
+/**
+ * An agent keeps its own `@camstack/server` closure current, with nobody driving it.
+ *
+ * Until now a closure reached an agent only when the HUB called `applyServerUpdate` on it. A
+ * freshly installed desktop agent boots the seed closure baked into the app and, being unpaired,
+ * had no hub to receive a fix from — not even the fix for its own unpaired boot (D857).
+ *
+ * The target version:
+ *  - UNPAIRED: the npm `latest` of `@camstack/server` — there is no hub to follow;
+ *  - PAIRED: the version the HUB runs (carried on the registration ack), never npm latest, so
+ *    the cluster has no hub/agent skew.
+ *
+ * It reuses the one updater (`AgentUpdateService` → stage → `scheduleAgentRestart`, lifecycle =
+ * respawn, D5), never downgrades, and treats a failed read as "unknown", never as "up to date"
+ * (D49, D393): the reason is logged and nothing changes. The cadence is the update-check
+ * constant; there is no retry loop (D3).
+ *
+ * Off switch: `CAMSTACK_AGENT_SELF_UPDATE=off` (or `0`/`false`).
+ */
+const index_js_1 = require("../server-root/index.js");
+function skip(reason, failedRead = false) {
+    return { action: 'skip', reason, failedRead };
+}
+function decideAgentSelfUpdate(input) {
+    if (input.running === null)
+        return skip('the running version is unknown', true);
+    let target;
+    let source;
+    if (input.paired) {
+        if (input.hubVersion === null) {
+            return skip('paired, but the hub version is unknown (no registration ack carrying it yet, or an older hub)', true);
+        }
+        target = input.hubVersion;
+        source = 'hub';
+    }
+    else {
+        if (!input.npmLatest.ok) {
+            return skip(`the registry read failed: ${input.npmLatest.reason}`, true);
+        }
+        target = input.npmLatest.version;
+        source = 'npm-latest';
+    }
+    const order = (0, index_js_1.compareSemver)(target, input.running);
+    if (order === 0)
+        return skip(`already running ${target} (${source})`);
+    if (order < 0)
+        return skip(`target ${target} (${source}) is older than running ${input.running}: never a downgrade`);
+    if (input.pendingVersion === target)
+        return skip(`${target} is already staged, awaiting restart`);
+    return { action: 'stage', version: target, source };
+}
+function agentSelfUpdateEnabled(env) {
+    const raw = env['CAMSTACK_AGENT_SELF_UPDATE']?.trim().toLowerCase();
+    return !(raw === 'off' || raw === '0' || raw === 'false' || raw === 'no');
+}
+/** One self-update pass. Every decision is logged with the versions; it never throws. */
+async function runAgentSelfUpdate(ports) {
+    const { log } = ports;
+    try {
+        if (!ports.enabled()) {
+            log.info('agent self-update: off (CAMSTACK_AGENT_SELF_UPDATE) — nothing checked');
+            return;
+        }
+        const paired = ports.isPaired();
+        const running = ports.runningVersion();
+        const hubVersion = ports.getHubServerVersion();
+        let npmLatest = { ok: false, reason: 'not needed' };
+        let pendingVersion = null;
+        if (!paired) {
+            const check = await ports.checkLatest();
+            pendingVersion = check.pendingVersion;
+            npmLatest =
+                check.error === null && check.latestVersion !== null
+                    ? { ok: true, version: check.latestVersion }
+                    : {
+                        ok: false,
+                        reason: check.error ?? 'the registry returned no version',
+                    };
+        }
+        log.info(`agent self-update: checked (${paired ? 'paired' : 'unpaired'}) running=${running ?? 'unknown'} ` +
+            `hub=${hubVersion ?? 'unknown'} npmLatest=${npmLatest.ok ? npmLatest.version : 'n/a'}`);
+        const decision = decideAgentSelfUpdate({
+            paired,
+            running,
+            npmLatest,
+            hubVersion,
+            pendingVersion,
+        });
+        if (decision.action === 'skip') {
+            const line = `agent self-update: skip — ${decision.reason}`;
+            if (decision.failedRead)
+                log.warn(line);
+            else
+                log.info(line);
+            return;
+        }
+        log.info(`agent self-update: staging ${decision.version} (${decision.source}) over ${running ?? 'unknown'}`);
+        const result = await ports.apply(decision.version);
+        if (result.accepted) {
+            log.info(`agent self-update: applied ${decision.version} (${result.outcome}) — restarting to swap the closure`);
+        }
+        else {
+            log.warn(`agent self-update: ${decision.version} not applied (${result.outcome}): ${result.message}`);
+        }
+    }
+    catch (err) {
+        log.warn(`agent self-update: failed — ${err instanceof Error ? err.message : String(err)}; nothing changed`);
+    }
+}

package/dist/agent/main.js

@@ -56,6 +56,9 @@ const agent_http_js_1 = require("./agent-http.js");
 const agent_node_certificates_js_1 = require("./agent-node-certificates.js");
 const agent_reconnect_js_1 = require("./agent-reconnect.js");
 const serial_queue_js_1 = require("./serial-queue.js");
+const agent_boot_mode_js_1 = require("./agent-boot-mode.js");
+const agent_self_update_js_1 = require("./agent-self-update.js");
+const update_check_scheduler_js_1 = require("../core/updates/update-check-scheduler.js");
 const agent_infra_capabilities_js_1 = require("./agent-infra-capabilities.js");
 const agent_service_js_1 = require("./agent-service.js");
 const agent_hub_addon_update_js_1 = require("./agent-hub-addon-update.js");
@@ -305,6 +308,9 @@ async function startAgent(configPath) {
     // AbortController for the upward hub registration retry loop — cancelled on
     // agent shutdown so we don't leak the retry loop after stop().
     const registerAbortController = new AbortController();
+    // The hub's `@camstack/server` version from the last `registerNode` ack (agent self-update).
+    let hubServerVersion = null;
+    let selfUpdateOnFirstAck = null;
     /**
      * Build the manifest for the agent's OWN in-process addons (those loaded by
      * bootCoreAddons and loadDeployedAddons that ended up in `loadedAddons` WITH
@@ -394,10 +400,15 @@ async function startAgent(configPath) {
         log: (msg) => console.log(`[Agent] ${msg}`),
         // The hub acked the manifest — the agent reached its registered state.
         // Run the single-copy GC sweep once (first ack only; no-op after).
-        onAcked: () => {
+        onAcked: (ackedHubServerVersion) => {
             if (hubConnectionStateOverride === 'certificate-rejected')
                 hubConnectionStateOverride = null;
+            hubServerVersion = ackedHubServerVersion;
             confirmAgentBootHealthy();
+            // Paired: the first ack is the first moment the hub's version is known.
+            const firstAck = selfUpdateOnFirstAck;
+            selfUpdateOnFirstAck = null;
+            firstAck?.();
         },
         onCertificateRefused: () => {
             if (hubConnectionStateOverride === 'certificate-rejected')
@@ -900,6 +911,44 @@ async function startAgent(configPath) {
             leafFingerprint: (0, agent_pairing_store_js_1.pairedLeafFingerprint)(config.configPath),
         });
     };
+    const addonsBooted = (0, agent_boot_mode_js_1.decideAgentBootMode)({ paired: (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath) }) === 'full';
+    // ── Self-update (agent-self-update.ts): keep this closure current with nobody driving it.
+    // Unpaired -> npm latest, at boot; paired -> the hub's version, at the first registration ack.
+    // Then on the update-check cadence (a periodic check, no retry loop). Lifecycle = respawn (D5).
+    const selfUpdatePorts = {
+        enabled: () => (0, agent_self_update_js_1.agentSelfUpdateEnabled)(process.env),
+        isPaired: () => (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath),
+        getHubServerVersion: () => hubServerVersion,
+        runningVersion: () => agentUpdateService.getRunningRootPackage().version,
+        checkLatest: async () => {
+            const check = await agentUpdateService.checkServerUpdate();
+            return {
+                latestVersion: check.latestVersion,
+                error: check.error,
+                pendingVersion: check.pendingVersion ?? null,
+            };
+        },
+        apply: async (version) => {
+            const result = await agentUpdateService.applyServerUpdate({ version });
+            return {
+                accepted: result.accepted,
+                outcome: result.outcome ?? 'unknown',
+                message: result.message,
+            };
+        },
+        log: {
+            info: (message) => consoleLogger.info(message, { tags: { nodeId: config.nodeId } }),
+            warn: (message) => consoleLogger.warn(message, { tags: { nodeId: config.nodeId } }),
+        },
+    };
+    if ((0, agent_pairing_store_js_1.isAgentPaired)(config.configPath)) {
+        selfUpdateOnFirstAck = () => void (0, agent_self_update_js_1.runAgentSelfUpdate)(selfUpdatePorts);
+    }
+    else {
+        void (0, agent_self_update_js_1.runAgentSelfUpdate)(selfUpdatePorts);
+    }
+    const selfUpdateTimer = setInterval(() => void (0, agent_self_update_js_1.runAgentSelfUpdate)(selfUpdatePorts), update_check_scheduler_js_1.DEFAULT_UPDATE_CHECK_INTERVAL_SECONDS * 1000);
+    selfUpdateTimer.unref();
     const localPairing = (0, agent_pairing_local_js_1.createLocalPairingAnnouncer)(config.dataDir, consoleLogger);
     const pairing = new system_1.AgentPairing({
         nodeId: config.nodeId,
@@ -912,7 +961,16 @@ async function startAgent(configPath) {
                 meta: { hubUrl: installed.hubUrl, hubAddress: installed.hubAddress },
             });
             // The completion is answered first; the wire is replaced right after.
-            const timer = setTimeout(() => void reconnect().then(advertise, advertise), 400);
+            const timer = setTimeout(() => {
+                if (addonsBooted) {
+                    void reconnect().then(advertise, advertise);
+                }
+                else {
+                    // Booted unpaired: no addon was started (agent-boot-mode.ts). Relaunch (D5) so
+                    // the core addons boot with the hub reachable.
+                    (0, agent_update_service_js_1.scheduleAgentRestart)(consoleLogger, 'paired with the hub', config.dataDir);
+                }
+            }, 400);
             timer.unref?.();
         },
         log: (message, meta) => consoleLogger.info(`pairing: ${message}`, meta ? { meta } : undefined),
@@ -951,6 +1009,40 @@ async function startAgent(configPath) {
     }).then((listener) => {
         agentHttpListener = listener;
     });
+    // Graceful shutdown
+    const shutdown = async () => {
+        console.log('[Agent] Shutting down...');
+        // Abort any in-flight upward hub registration retry loop.
+        registerAbortController.abort();
+        // Dispose the UDS event bridge to remove the parent-bus subscriber and
+        // clear the child-event handler, preventing subscriber leaks on shutdown.
+        udsEventBridgeDispose?.();
+        udsEventBridgeDispose = null;
+        for (const [, entry] of loadedAddons) {
+            if (entry.addon?.shutdown) {
+                try {
+                    await entry.addon.shutdown();
+                }
+                catch {
+                    /* */
+                }
+            }
+        }
+        // Withdraw the mDNS advertisement, then stop accepting new HTTP/HTTPS connections before
+        // the broker goes away.
+        await agentMdns.stop().catch(() => undefined);
+        await agentHttpListener?.close().catch(() => undefined);
+        await broker.stop();
+        process.exit(0);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    // An unpaired agent has no hub to read settings from (D857): serve pairing only and
+    // relaunch after the certificate is installed (D5). See agent-boot-mode.ts.
+    if (!addonsBooted) {
+        console.log(`[Agent] Node "${config.nodeId}" is unpaired - serving pairing only; addons boot after pairing`);
+        return;
+    }
     // ── Phase 1: Load core infrastructure addons (in-process) ──
     // storage + settings + metrics + hub-forwarder (log destination)
     await bootCoreAddons(broker, config, capabilityRegistry, loadedAddons, loggerFactory);
@@ -1003,34 +1095,6 @@ async function startAgent(configPath) {
         }
     });
     console.log(`[Agent] Node "${config.nodeId}" (name="${config.name}") ready — ${loadedAddons.size} addon(s) loaded`);
-    // Graceful shutdown
-    const shutdown = async () => {
-        console.log('[Agent] Shutting down...');
-        // Abort any in-flight upward hub registration retry loop.
-        registerAbortController.abort();
-        // Dispose the UDS event bridge to remove the parent-bus subscriber and
-        // clear the child-event handler, preventing subscriber leaks on shutdown.
-        udsEventBridgeDispose?.();
-        udsEventBridgeDispose = null;
-        for (const [, entry] of loadedAddons) {
-            if (entry.addon?.shutdown) {
-                try {
-                    await entry.addon.shutdown();
-                }
-                catch {
-                    /* */
-                }
-            }
-        }
-        // Withdraw the mDNS advertisement, then stop accepting new HTTP/HTTPS connections before
-        // the broker goes away.
-        await agentMdns.stop().catch(() => undefined);
-        await agentHttpListener?.close().catch(() => undefined);
-        await broker.stop();
-        process.exit(0);
-    };
-    process.on('SIGTERM', shutdown);
-    process.on('SIGINT', shutdown);
 }
 // ---------------------------------------------------------------------------
 // Phase 1: Boot core addons (storage, settings, metrics — NO winston)
@@ -1217,7 +1281,10 @@ async function loadClusterCapableAddons(broker, config, capabilityRegistry, load
             try {
                 await broker.call('$process.spawnRunner', {
                     runnerId: groupId,
-                    addons: addons.map((a) => ({ addonId: a.addonId, addonDir: a.addonDir })),
+                    addons: addons.map((a) => ({
+                        addonId: a.addonId,
+                        addonDir: a.addonDir,
+                    })),
                 });
                 // Shared with the reload path (`ensureGroupRunner`) so the boot and
                 // reload registrations can never drift — the drift was the in-process

package/dist/core/moleculer/hub-server-version.js

@@ -0,0 +1,68 @@
+"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.readServerVersionFrom = readServerVersionFrom;
+exports.readHubServerVersion = readHubServerVersion;
+/**
+ * The `@camstack/server` version this hub runs, carried on every `$hub.registerNode` ack so an
+ * agent can align its own closure to it (agent self-update). Read once from the running
+ * package.json (`dist/core/moleculer/` -> `../../../package.json`); null when it cannot be read —
+ * the ack then simply omits it and the agent says "hub version unknown" instead of guessing.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const index_js_1 = require("../../server-root/index.js");
+function readServerVersionFrom(packageJsonPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        if (typeof raw !== 'object' || raw === null)
+            return null;
+        const name = Reflect.get(raw, 'name');
+        const version = Reflect.get(raw, 'version');
+        if (name !== index_js_1.SERVER_ROOT_PACKAGE_NAME)
+            return null;
+        return typeof version === 'string' && version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+let cached;
+function readHubServerVersion() {
+    if (cached === undefined) {
+        cached = readServerVersionFrom(path.resolve(__dirname, '..', '..', '..', 'package.json'));
+    }
+    return cached;
+}

package/dist/core/moleculer/moleculer.service.js

@@ -11,6 +11,7 @@ const core_cap_bridge_js_1 = require("../../api/trpc/core-cap-bridge.js");
 const agent_readiness_pull_js_1 = require("./agent-readiness-pull.js");
 const agent_registration_request_js_1 = require("./agent-registration-request.js");
 const hub_mesh_guard_js_1 = require("./hub-mesh-guard.js");
+const hub_server_version_js_1 = require("./hub-server-version.js");
 const cap_call_fn_js_1 = require("./cap-call-fn.js");
 const cap_route_authority_js_1 = require("./cap-route-authority.js");
 class MoleculerService {
@@ -270,6 +271,8 @@ class MoleculerService {
             onUnregisterNode: (nodeId) => {
                 this.removeNodeFromRegistry(nodeId);
             },
+            // The ack carries the hub's closure version so an agent aligns to it (agent self-update).
+            getServerVersion: () => (0, hub_server_version_js_1.readHubServerVersion)(),
             // D857: a node registers only itself, and only with a certificate identity.
             meshIdentity: this.meshGuard.gate,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.675",
+  "version": "1.2.677",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
     "@camstack/addon-post-analysis": "1.2.649",
     "@camstack/develop": "0.1.38",
     "@camstack/sdk": "1.2.154",
-    "@camstack/system": "1.2.506",
+    "@camstack/system": "1.2.508",
     "@camstack/types": "1.2.436",
     "@camstack/ui-library": "1.2.345",
     "@fastify/compress": "^9.0.0",